@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/guides/core-concepts/persistent/search-meilisearch.md

@@ -0,0 +1,185 @@
+# Search & Meilisearch
+
+IGNIS ships a **meilisearch connector** under `@venizia/ignis/meilisearch`. It shares the entire search paradigm with the Typesense connector - the same `@model`/`@repository`/`@datasource` decorators, the same `defineSearchCollection` field DSL, the same repository tiers and controller factory - all of which live in the engine-neutral `@venizia/ignis/search` module.
+
+What it does **not** share is the pretence that the two engines are the same. Where Meilisearch differs from Typesense, IGNIS surfaces the difference rather than papering over it.
+
+> [!IMPORTANT] Subpath-only import
+> `meilisearch` is an **optional peer dependency**. The connector is never re-exported from the `@venizia/ignis` root barrel, so apps that don't use it never pull in the client.
+>
+> ```typescript
+> import { MeilisearchDataSource } from '@venizia/ignis/meilisearch';
+> import { BaseSearchEntity, defineSearchCollection, field } from '@venizia/ignis/search';
+> ```
+>
+> Install it alongside the framework:
+>
+> ```bash
+> bun add meilisearch
+> ```
+
+## Defining a Collection
+
+The collection DSL is the same one the Typesense connector uses. What changes is which flags matter.
+
+```typescript
+import { BaseSearchEntity, defineSearchCollection, field } from '@venizia/ignis/search';
+import { model } from '@venizia/ignis';
+
+@model({ type: 'entity' })
+export class ArticleDocument extends BaseSearchEntity {
+  static override schema = defineSearchCollection({
+    name: 'articles',
+    fields: [
+      field.id(),
+      field.string('title', { searchable: true }),
+      field.string('body', { searchable: true }),
+      field.number('score', { filterable: true, sortable: true }),
+    ],
+    synonyms: [{ id: 'jacket', synonyms: ['jacket', 'coat', 'blazer'] }],
+  });
+}
+```
+
+Meilisearch is **schemaless**: it has no field schema at all. A collection therefore compiles to an index uid plus a settings object, not to a list of typed fields.
+
+| DSL | Meilisearch |
+| --- | --- |
+| `field.id()` | `primaryKey` |
+| `searchable: true` | `searchableAttributes` |
+| `filterable: true` | `filterableAttributes` |
+| `sortable: true` | `sortableAttributes` |
+| `field.vector(...)` | an `embedders` entry |
+| `synonyms` | a flat `synonyms` dictionary |
+| `engineOverrides.meilisearch` | merged last onto settings |
+
+The `searchable` and `filterable` flags are **load-bearing here** and are silently dropped by the Typesense compiler, which indexes every field by default. If no field declares `searchable`, IGNIS leaves `searchableAttributes` at Meilisearch's own `['*']` default rather than emitting an empty array, which would disable search entirely.
+
+## The DataSource
+
+```typescript
+import { datasource } from '@venizia/ignis';
+import { MeilisearchDataSource } from '@venizia/ignis/meilisearch';
+
+@datasource()
+export class ArticleSearchDataSource extends MeilisearchDataSource {}
+```
+
+No `driver` in the decorator, and that is not an omission. A relational datasource has to name one, because a single `BasePostgresDataSource` runs on either `pg` or `postgres` and something must pick. A search datasource has already picked: `extends MeilisearchDataSource` **is** the engine reference, and it is what carries the `meilisearch` package into your bundle. Naming the engine twice would just be a second chance to disagree with yourself.
+
+Configured through `IMeilisearchDataSourceSettings`:
+
+```typescript
+new ArticleSearchDataSource({
+  name: 'search',
+  config: {
+    host: process.env.APP_ENV_MEILISEARCH_HOST,
+    apiKey: process.env.APP_ENV_MEILISEARCH_API_KEY,
+    taskTimeoutMs: 5 * 60_000,
+  },
+});
+```
+
+Provisioning is governed by the same `APP_ENV_AUTO_PROVISION_COLLECTION` flag as every other search datasource. It is **off** unless set to `true` or `1`.
+
+## Writes await their task
+
+Every Meilisearch write returns a `taskUid` and the document is **not searchable until that task reaches `succeeded`**. Typesense writes are synchronous.
+
+IGNIS resolves this by awaiting the task inside the connector, so the repository contract is identical on both engines:
+
+```typescript
+await repository.create({ data: article });
+// The document is retrievable here. No sleep, no retry loop.
+```
+
+The cost is real and worth knowing: each write polls until its task completes. The client SDK's own `waitForTask` defaults to a 5-second timeout, which is far too short for a bulk import, so IGNIS never relies on it - configure `taskTimeoutMs` instead. A task that fails raises the standard sanitized dependency error; one that never terminates raises a `core.search_engine.task_timeout`.
+
+If you want fire-and-forget writes, reach the raw client:
+
+```typescript
+const client = dataSource.getClient(); // the raw `Meilisearch` SDK client
+await client.index('articles').addDocuments([article]); // returns a taskUid, does not await
+```
+
+## `count()` is exact
+
+Meilisearch's search route reports `estimatedTotalHits`, and its exhaustive `totalHits` is capped by the index-level `pagination.maxTotalHits` setting (default **1000**).
+
+IGNIS never counts through the search route. `count()` calls `POST /documents/fetch` with `limit: 0` and reads the exact `total`, which the engine's own documentation states is unaffected by `maxTotalHits`. A filtered count over 50,000 matching documents returns 50,000.
+
+`ISearchResult.isFoundExact` reports the truth for the **search** route: always `true` on Typesense, and on Meilisearch `true` only in the exhaustive page mode. It travels all the way out through the generated REST response, so an API consumer paginating your endpoint can tell an estimate from an exhaustive count.
+
+## Capability differences are compile-time, not runtime
+
+`SearchBaseRepository` is generic on its datasource, so `this.connector` resolves to the concrete connector type. Engine-only verbs are therefore a matter for the compiler, not a runtime capability check:
+
+```typescript
+class ArticleRepository extends DefaultSearchRepository<TArticle, MeilisearchDataSource> {
+  swap() {
+    return this.connector.swap.indexes({ pairs: [['articles', 'articles_next']] }); // required
+    // this.connector.alias -> compile error: property does not exist
+  }
+}
+
+class PortableRepository extends DefaultSearchRepository<TDocument> {
+  swap() {
+    return this.connector.alias?.upsert({ name, collection }); // the `?.` is forced
+  }
+}
+```
+
+| Verb group | Typesense | Meilisearch |
+| --- | --- | --- |
+| `collection`, `document`, `search`, `multiSearch` | required | required |
+| `document.updateBy` | native | emulated (see below) |
+| `document.count` | `per_page: 0` search | `documents/fetch` `limit: 0` |
+| `alias` | required | **absent** |
+| `swap` | absent | **required** |
+| `synonymSet` (named, linkable) | required | absent |
+| `synonyms` (flat dictionary) | absent | required |
+
+## Behaviours to know before you commit
+
+**`create()` rejects duplicates, but the check is not atomic.** Meilisearch's `addDocuments` is add-or-replace; it has no conditional insert. To honour the neutral contract (Typesense's `create()` returns 409 on a duplicate id), IGNIS reads the id first and throws `409 core.search_engine.already_exists` if it exists. Two concurrent creates of the same id can both pass that check, and the second write wins. If you want last-write-wins, call `upsert()` and say so.
+
+**`updateById` on a missing id throws `404`, it does not upsert.** Meilisearch's `updateDocuments` is add-or-update, so a missing id would silently fabricate a record. IGNIS checks existence before any write and throws `404 core.search_engine.not_found` instead - matching Typesense and the neutral contract. (This is the deliberate search-family divergence from the PostgreSQL connector, where a missing-id `updateById` is a silent `{ count: 0 }`.)
+
+**`updateBy` is emulated and is not atomic.** Meilisearch has no update-by-filter endpoint. IGNIS pages primary keys out of `documents/fetch`, then issues merge-`PUT` batches. A concurrent write to a matched document may be overwritten. The experimental `documents/edit` route would do this server-side, but it is gated behind a feature flag, is documented as breaking between minor versions, and has an open correctness bug - so IGNIS does not use it.
+
+**`import`/`createAll` is batch-atomic.** Documents are added in batches, each batch's task awaited before the next starts. A batch either lands whole or throws, so `count.fail` is structurally always `0`. When a batch fails, the batches after the failure point did not land and the thrown error's `details` carry `{ totalCount, processedCount }` so a caller can resume from `processedCount` rather than replaying the whole import.
+
+**Meilisearch error classification reads the real SDK error shape.** A thrown `MeilisearchApiError` carries its body under `error.cause.code` and its HTTP status under `error.response.status`, not top-level `code`/`httpStatus`. Reading only the flat shape misclassifies a legitimate 404 (for example the existence probe inside `create()`) as an unrelated 503 dependency failure; the classifier checks both the flat shape (task-error responses) and the nested `cause`/`response` shape (thrown SDK errors).
+
+**`createCollection`/`ensureCollection` are idempotent.** An `index_already_exists` failure is tolerated and logged rather than thrown, so boot-time provisioning against an already-provisioned collection (a restart, a second app instance) succeeds instead of crashing.
+
+**`hiddenProperties` is supported on Meilisearch via JS-side stripping, not engine-side exclusion.** Meilisearch has no per-query field-exclusion param (only the index-level `displayedAttributes` setting), so the dialect does not attempt to translate `hiddenFields` - it deliberately passes them through untranslated. The guarantee is upheld one layer up: `SearchBaseRepository` strips hidden fields from every document `find()`/`findOne()`/`search()` returns before it reaches the caller, so a model with `hiddenProperties` works identically to Typesense from the caller's point of view - no throw, no leak.
+
+**A geopoint field must be named `_geo`.** Meilisearch supports exactly one geo field, shaped `{ lat, lng }`, under that reserved name. The compiler throws on any other name, and on a second geo field.
+
+**Vector distance is cosine only.** `field.vector(..., { distance: 'l2' })` throws.
+
+**Engine-specific knobs never reach the neutral schema.** The neutral search input carries only fields every engine supports; Typesense-only tuning (`num_typos`, `pinned_hits`, `preset`, ...) travels through `engineParams` with wire names and is passed verbatim to the engine - so sending Typesense knobs to a Meilisearch datasource is a caller error, and the dialect still raises a named error for known-foreign knobs arriving via untyped input. Use `engineParams` (or `mode: 'raw'`) for Meilisearch-native tuning such as `rankingScoreThreshold`.
+
+**`multiSearch` batches but does not merge.** `union: true` throws. Meilisearch merges results through its `federation` option, which this connector does not model, so `getCapabilities()` honestly reports `union: false`.
+
+**Result grouping does not exist.** `groupBy`, `groupLimit` and `groupMissingValues` all throw. Meilisearch's `distinct` search param deduplicates on one attribute; it does not group hits. Reach the raw client if that is what you want.
+
+## Vector and hybrid search
+
+Vector fields compile to `embedders`, and `mode: 'semantic'` / `mode: 'hybrid'` translate to Meilisearch's `hybrid: { semanticRatio, embedder }` plus an optional `vector`. The neutral `alpha` maps to `semanticRatio`; `mode: 'semantic'` pins it to `1.0`, and an omitted `alpha` on `hybrid` defaults to `0.5`.
+
+This path is compiled and translated but is **not exercised end to end** by the framework's test suite, and Meilisearch has moved its vector store in and out of `/experimental-features` across server versions. Verify against your target server version before depending on it.
+
+## Adding another search engine
+
+The neutral paradigm lives in `@venizia/ignis/search` and imports no engine. To add one:
+
+1. Implement `ISearchConnector`, declaring **only** the optional verb groups your engine actually has.
+2. Write a compiler from `ISearchCollectionDefinition` to the engine's schema or settings.
+3. Write an `ISearchQueryDialect` - `build`, `toWhere`, `applySearchInput`, `toWireParams`.
+4. Subclass `BaseSearchDataSource`.
+5. Register a sub-path export and an optional peer dependency.
+6. Pass `runConnectorConformance`.
+
+That last step is the contract. A seam only one engine can satisfy is not a seam.

package/content/guides/core-concepts/persistent/search-typesense.md

@@ -0,0 +1,431 @@
+# Search & Typesense
+
+IGNIS ships a **typesense connector** under `@venizia/ignis/typesense` for full-text and faceted search. It plugs into the same `@model`/`@repository`/`@datasource` decorators as the PostgreSQL connector, but documents replace Drizzle tables and the query surface is intentionally narrower - search engines are not relational databases.
+
+> [!IMPORTANT] Subpath-only import
+> `typesense` is an **optional peer dependency** - the typesense connector is not re-exported from the `@venizia/ignis` root barrel (unlike `postgres`), so apps that don't use search never pull in the `typesense` client. Always import from `@venizia/ignis/typesense`:
+>
+> ```typescript
+> import {
+>   TypesenseDataSource,
+>   BaseSearchEntity,
+>   defineSearchCollection,
+>   field,
+> } from '@venizia/ignis/typesense';
+> ```
+>
+> See [Connectors](/references/base/connectors) for the full dual-door export model.
+
+## Defining a Search Collection
+
+Instead of a Drizzle `pgTable`, define a collection with `defineSearchCollection` and the `field` DSL:
+
+```typescript
+// src/models/entities/article.model.ts
+import { model } from '@venizia/ignis';
+import {
+  BaseSearchEntity,
+  defineSearchCollection,
+  field,
+  TSearchDocument,
+} from '@venizia/ignis/typesense';
+
+@model({
+  type: 'entity',
+  settings: {
+    hiddenProperties: ['internalNote'],
+    defaultFilter: { where: { status: 'published' } },
+    defaultLimit: 20,
+  },
+})
+export class ArticleDocument extends BaseSearchEntity<typeof ArticleDocument.schema> {
+  static override schema = defineSearchCollection({
+    name: 'articles',
+    fields: [
+      field.id(),
+      field.string('title', { searchable: true, sortable: true }),
+      field.string('content', { searchable: true }),
+      field.string('category', { facet: true }),
+      field.string('status', { facet: true }),
+      field.number('views', { sortable: true, filterable: true }),
+      field.number('publishedAt', { sortable: true, filterable: true }),
+      field.strings('tags', { facet: true, optional: true }),
+      field.string('internalNote', { optional: true }),
+    ],
+    defaultSort: 'publishedAt',
+  });
+}
+
+export type TArticleDocument = TSearchDocument<typeof ArticleDocument.schema>;
+```
+
+The same `@model` settings you use with Drizzle entities - `hiddenProperties`, `defaultFilter`, `defaultLimit` - work identically here. `hiddenProperties` compiles to Typesense's `exclude_fields`; `defaultFilter.where` is AND-merged into every read's `filter_by` unless the caller passes `shouldSkipDefaultFilter: true`.
+
+### The `field` DSL
+
+`field.*` covers the scalar and array wire types plus a `vector` builder for semantic search - there is no date or object builder:
+
+| Builder                        | Wire type                       | Notes                                                                                                                                                                                 |
+| ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `field.id()`                   | `string`                        | Takes no arguments; hardcoded `{ name: 'id', type: 'string' }`. Auto-prepended if you omit it.                                                                                        |
+| `field.string(name, flags?)`   | `string`                        |                                                                                                                                                                                       |
+| `field.strings(name, flags?)`  | `string[]`                      |                                                                                                                                                                                       |
+| `field.number(name, flags?)`   | `number`                        |                                                                                                                                                                                       |
+| `field.numbers(name, flags?)`  | `number[]`                      |                                                                                                                                                                                       |
+| `field.boolean(name, flags?)`  | `boolean`                       |                                                                                                                                                                                       |
+| `field.booleans(name, flags?)` | `boolean[]`                     |                                                                                                                                                                                       |
+| `field.geopoint(name, flags?)` | `geopoint` (`[number, number]`) |                                                                                                                                                                                       |
+| `field.vector(name, opts)`     | `float[]`                       | Embedding vector for semantic/hybrid search. Its `opts` carry `dimensions`/`distance`/`embed` rather than the shared flags - see [Vector Fields](#vector-fields-for-semantic-search). |
+
+Each `flags` object may set `searchable`, `filterable`, `facet`, `sortable`, `optional` (all `boolean`). Note: `searchable`/`filterable` have no direct Typesense wire equivalent (Typesense indexes every field by default) and are dropped at compile time - only `facet`, `optional`, and `sortable` (mapped to Typesense's `sort`) actually reach the compiled collection schema. They're still worth setting for documentation/intent and for future engines that do distinguish them.
+
+`defineSearchCollection` validates at call time: throws on an empty `name`, empty `fields`, duplicate field names, a non-`string` `id` field, or an unknown `defaultSort` field reference.
+
+### `TSearchDocument<T>`
+
+Derives the document's TypeScript shape directly from the collection definition - no hand-maintained duplicate type:
+
+```typescript
+export type TArticleDocument = TSearchDocument<typeof ArticleDocument.schema>;
+// {
+//   id: string;
+//   title: string;
+//   content: string;
+//   category: string;
+//   status: string;
+//   views: number;
+//   publishedAt: number;
+//   tags?: string[];       // optional: true -> optional property
+//   internalNote?: string; // optional: true -> optional property
+// }
+```
+
+`id` is always `string` and required. Every non-`optional` field is required; every `optional: true` field becomes an optional property.
+
+## Vector Fields for Semantic Search
+
+`field.vector(name, opts)` declares a `float[]` embedding column. There are two ways to populate it.
+
+**Server-side auto-embedding** - Typesense builds the vector from other fields at index time, so your app never computes an embedding. Point `embed.from` at the source fields and name an embedding model:
+
+```typescript
+// Local built-in model - runs on the Typesense server, no API key, no external calls:
+field.vector('embedding', {
+  embed: { from: ['title', 'content'], model: { name: 'ts/all-MiniLM-L6-v2' } },
+});
+
+// Remote provider - the API key is read from env, never hardcoded. This example is Gemini via
+// Google's OpenAI-compatible endpoint (Typesense's `openai/` provider plus a custom `url`):
+field.vector('embedding', {
+  embed: {
+    from: ['title', 'content'],
+    model: {
+      url: 'https://generativelanguage.googleapis.com/v1beta/openai',
+      name: 'openai/gemini-embedding-001',
+      apiKey: process.env.APP_ENV_GOOGLE_API_KEY,
+    },
+  },
+});
+```
+
+The `model` config is camelCase and maps to Typesense's snake_case `model_config` at compile time (`name` becomes `model_name`, `apiKey` becomes `api_key`, `accessToken` becomes `access_token`, and so on); any provider field not modeled is passed through unchanged. Never hardcode `apiKey` into a committed schema - source it from an environment variable.
+
+**Client-provided vectors** - you compute the embedding yourself and send it with each document. Declare `dimensions` and a distance metric instead of `embed`:
+
+```typescript
+import { VectorDistances } from '@venizia/ignis/typesense';
+
+field.vector('embedding', { dimensions: 384, distance: VectorDistances.COSINE });
+// VectorDistances: COSINE ('cosine'), INNER_PRODUCT ('ip'), L2 ('l2')
+```
+
+An auto-embedded field (one with `embed`) is **omitted from `TSearchDocument`** - the server owns it, so it never appears in your create/update payloads. A client-provided vector field (dimensions only, no `embed`) stays in the document type as `number[]`.
+
+See [Searching](#searching-with-search-mode) for querying these fields with `mode: 'semantic'` and `mode: 'hybrid'`.
+
+## Synonyms
+
+Declare synonym sets on the collection; they are provisioned alongside it at `configure()`:
+
+```typescript
+static override schema = defineSearchCollection({
+  name: 'articles',
+  fields: [ /* ... */ ],
+  synonyms: [
+    // Multi-way (no `root`): every term matches the others.
+    { id: 'ml', synonyms: ['ml', 'machine learning', 'deep learning'] },
+    // One-way (`root` set): a query for the root also matches the synonyms, not the reverse.
+    { id: 'js', root: 'javascript', synonyms: ['js', 'ecmascript', 'nodejs'] },
+  ],
+});
+```
+
+Declarative `synonyms` are provisioned as one **synonym set** per collection (named `<collection>_synonyms`) and linked to it - matching Typesense v30+'s global synonym-sets model (the pre-v30 per-collection synonyms API was removed). For runtime management outside the declarative schema, the connector exposes the synonym-set verbs through the raw client escape hatch:
+
+```typescript
+const connector = repository.dataSource.getConnector();
+await connector.upsertSynonymSet({
+  name: 'articles_synonyms',
+  items: [{ id: 'db', synonyms: ['db', 'database', 'datastore'] }],
+});
+await connector.linkSynonymSets({ collection: 'articles', synonymSets: ['articles_synonyms'] });
+// getSynonymSet({ name }) / listSynonymSets() / deleteSynonymSet({ name }) round out the set.
+```
+
+## Configuring a DataSource
+
+```typescript
+// src/datasources/search.datasource.ts
+import { datasource } from '@venizia/ignis';
+import { TypesenseDataSource } from '@venizia/ignis/typesense';
+import { applicationEnvironment, int } from '@venizia/ignis-helpers';
+
+@datasource()
+export class SearchDataSource extends TypesenseDataSource {
+  constructor() {
+    super({
+      name: SearchDataSource.name,
+      config: {
+        nodes: [
+          {
+            host: applicationEnvironment.get<string>('APP_ENV_TYPESENSE_HOST'),
+            port: int(applicationEnvironment.get<string>('APP_ENV_TYPESENSE_PORT')),
+            protocol: applicationEnvironment.get<string>('APP_ENV_TYPESENSE_PROTOCOL'),
+          },
+        ],
+        apiKey: applicationEnvironment.get<string>('APP_ENV_TYPESENSE_API_KEY'),
+      },
+      // NO schema property - collections auto-discovered from @repository bindings, same convention as postgres.
+    });
+  }
+}
+```
+
+No `driver` in the decorator, and that is not an omission. A relational datasource has to name one, because a single `BasePostgresDataSource` runs on either `pg` or `postgres` and something must pick. A search datasource has already picked: `extends TypesenseDataSource` **is** the engine reference, and it is what carries the `typesense` package into your bundle. Naming the engine twice would just be a second chance to disagree with yourself.
+
+`TypesenseDataSource` extends `BaseSearchDataSource` (adds auto-discovery/provisioning) which extends `AbstractSearchDataSource` (engine contract: `getDriver()`, `getQueryDialect()`, `compileCollection()`, `ensureCollection()`) which extends the engine-neutral `AbstractDataSource`. Since `TypesenseDataSource` never overrides `beginTransaction()`, it inherits the neutral `NotSupported` default - see [Connectors](/references/base/connectors).
+
+On `configure()`, the datasource auto-provisions every discovered collection (`ensureCollection()` per definition, plus any declared `synonyms`) unless constructed with `autoProvision: false`.
+
+`getCapabilities()` reports what the engine supports so callers can probe before relying on a feature across engines:
+
+```typescript
+dataSource.getCapabilities();
+// { transactions: false, search: { vector: true, multi: true, union: true, synonyms: true } }
+```
+
+## Repository Tiers
+
+Mirrors the PostgreSQL connector's ladder, but for documents instead of rows:
+
+```
+AbstractRepository (engine-neutral)
+  -> TypesenseBaseRepository (narrows dataSource/entity to TypesenseDataSource/BaseSearchEntity)
+    -> ReadableSearchRepository (count, existsWith, find, findOne, findById, search<TResult>())
+      -> PersistableSearchRepository (create, createAll, updateById, updateAll, import)
+        -> DefaultSearchRepository (+ deleteById, deleteAll)
+```
+
+```typescript
+// src/repositories/article.repository.ts
+import { SearchDataSource } from '@/datasources/search.datasource';
+import { ArticleDocument, TArticleDocument } from '@/models/entities';
+import { repository } from '@venizia/ignis';
+import { DefaultSearchRepository } from '@venizia/ignis/typesense';
+
+@repository({ model: ArticleDocument, dataSource: SearchDataSource })
+export class ArticleRepository extends DefaultSearchRepository<TArticleDocument> {
+  findByCategory(opts: { category: string }) {
+    return this.find({ filter: { where: { category: opts.category } } });
+  }
+}
+```
+
+`find()`/`findOne()`/`findById()`/`count()`/`existsWith()` accept the same `TFilter`/`TWhere` shape as PostgreSQL repositories - the `TypesenseQueryDialect` translates `where` into Typesense's `filter_by` syntax, `order` into `sort_by` (max 3 fields - a Typesense limit), `limit`/`skip` into `per_page`/`page`, and `fields` into `include_fields`. `filter.include` is **not supported** and throws - there is no relation model for documents.
+
+### Envelope differences vs. PostgreSQL
+
+|                                            | PostgreSQL repositories                             | Search repositories                                                                                                                            |
+| ------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Range queries                              | Extra `COUNT(*)` query for `shouldQueryRange: true` | Single search call already returns `found` - no second query needed                                                                            |
+| `updateAll`/`deleteAll` with empty `where` | Requires `force: true`                              | `updateAll` **refuses** an unfiltered bulk update outright (throws, no override); `deleteAll` with no effective filter (no `where` and no `@model defaultFilter`) also throws unless `options.force: true` is passed - only then does it truncate the whole collection |
+| Returning updated/deleted rows             | Native SQL `RETURNING`                              | No `RETURNING` equivalent - `updateAll`/`deleteAll` are **count-only**: `data` is always `null` and `shouldReturn` is rejected at the type level (no hidden engine read is bolted on). Read the affected documents explicitly before the write when you need them |
+| `createAll`                                | Native bulk insert, returns each row                | Delegates to Typesense's bulk import; "created" rows are the input rows whose per-row response didn't report `success: false`                  |
+
+### Write error semantics (shared by both search engines)
+
+- **`create()` with a duplicate id throws `409` (`messageCode: 'core.search_engine.already_exists'`)** on both Typesense and Meilisearch - a duplicate is a conflict, never a silent overwrite. If you want last-write-wins, call `upsert()` explicitly. (On Meilisearch the pre-check is not atomic - see the [Meilisearch guide](./search-meilisearch); use `upsert()` when concurrent same-id creates are possible.)
+- **`updateById()` against a missing id throws `404` (`messageCode: 'core.search_engine.not_found'`)** on both engines. This is the deliberate divergence from the PostgreSQL connector, where a missing-id `updateById` is a silent `{ count: 0 }`.
+- **`deleteById()` against a missing id is silent** (`{ count: 0, data: null }`), matching the relational connectors.
+
+## Searching with `search({ mode })`
+
+Beyond the `find()` tier (filter-only reads that return documents), `search()` is the search-engine entry point. It is one method whose shape is selected by `mode`, so TypeScript narrows the options to just that mode's fields - you never juggle every parameter at once. `mode` defaults to `keyword`.
+
+The `keyword`/`semantic`/`hybrid` modes reuse the same filter translation as `find()` (`@model defaultFilter`, `hiddenProperties`, `where`/`order`/`limit`), then layer the search term or vector on top. The `raw` mode is a full passthrough with no translation.
+
+**`keyword`** - full-text search:
+
+```typescript
+await repository.search({
+  mode: 'keyword',
+  query: 'renewable energy',
+  queryBy: ['title', 'content'], // which fields to match
+  filter: { where: { published: true }, limit: 20 }, // optional, same TFilter as find()
+});
+```
+
+**`semantic`** - vector search. Supply a precomputed vector, or `queryText` against a server-side auto-embed field:
+
+```typescript
+// Client-provided vector:
+await repository.search({ mode: 'semantic', vectorField: 'embedding', nearVector: [0.12, ...], k: 10 });
+
+// Server-side auto-embed (the field was declared with `embed`) - Typesense embeds the text for you:
+await repository.search({ mode: 'semantic', vectorField: 'embedding', queryText: 'renewable energy', k: 10 });
+```
+
+**`hybrid`** - keyword and vector blended. `alpha` weights vector against text (0 to 1):
+
+```typescript
+await repository.search({
+  mode: 'hybrid',
+  query: 'renewable energy',
+  queryBy: ['title'],
+  vectorField: 'embedding',
+  alpha: 0.5,
+  k: 10,
+});
+```
+
+> [!NOTE]
+> `semantic` and `hybrid` default `prefix=false`: prefix matching is meaningless for vector search, and remote embedders (OpenAI/Google/...) reject it (`Prefix search is not supported for remote embedders`). Pass `engineParams: { prefix: true }` to override.
+
+**`raw`** - native Typesense params, no `TFilter`/`defaultFilter`/`hiddenProperties` translation. Use it for any engine feature the modes above do not model:
+
+```typescript
+await repository.search({
+  mode: 'raw',
+  params: { q: '*', filter_by: 'price:>100', vector_query: 'embedding:([...], k:10)' },
+});
+```
+
+> [!NOTE]
+> `raw` skips `@model defaultFilter`, so it can surface documents the `find()`/`keyword` tiers would hide (for example non-`published` articles). Apply any tenant or visibility filtering explicitly in `params.filter_by` when exposing raw search over HTTP.
+
+All non-`raw` modes accept the same optional camelCase tuning fields, mapped to Typesense's snake_case at the dialect boundary: faceting (`facetBy`, `facetQuery`, `maxFacetValues`), highlighting (`highlightFields`, `highlightFullFields`, `highlightStartTag`/`highlightEndTag`, `snippetThreshold`), grouping (`groupBy`, `groupLimit`, `groupMissingValues`), and `queryByWeights`. These are the ENGINE-NEUTRAL fields - every search engine supports them.
+
+Typesense-specific tuning (`num_typos`, `prefix`, `infix`, `use_cache`, `cache_ttl`, `exhaustive_search`, `pinned_hits`, `hidden_hits`, `prioritize_exact_match`, `drop_tokens_threshold`, `preset`) goes through `engineParams`, passed verbatim to the engine with WIRE names - the neutral input schema no longer carries knobs only one engine understands:
+
+```typescript
+await repository.search({
+  mode: 'keyword',
+  query: 'shoes',
+  queryBy: ['name'],
+  engineParams: { num_typos: 1, prefix: false, preset: 'listing' },
+});
+```
+
+```typescript
+await repository.search({
+  mode: 'keyword',
+  query: 'shoes',
+  queryBy: ['name'],
+  facetBy: ['brand', 'color'], // faceted counts
+  highlightFields: ['name'], // marked matches
+  groupBy: ['brand'],
+  groupLimit: 3, // grouped results
+});
+```
+
+`mode` values are also available as the `SearchModes` const (`SearchModes.KEYWORD`/`SEMANTIC`/`HYBRID`/`RAW`) if you prefer named constants over string literals.
+
+### The result envelope
+
+`search()` returns the engine's search envelope (unlike `find()`, which returns documents):
+
+```typescript
+interface ISearchResult<TDocument extends object = object> {
+  found: number;
+  hits?: Array<{ document: TDocument; highlight?: unknown; textMatch?: number }>;
+  facetCounts?: unknown[];
+  groupedHits?: unknown[];
+}
+```
+
+## Cross-Collection Multi-Search
+
+A single search targets one collection, so it lives on the repository. Searching **many** collections in one round trip lives on the **datasource**:
+
+```typescript
+await repository.dataSource.multiSearch({
+  searches: [
+    { collection: 'products', query: 'shoes', queryBy: ['name'] },
+    { collection: 'brands', query: 'shoe' },
+  ],
+  commonParams: { perPage: 20 }, // optional defaults applied to every search
+});
+```
+
+Federated by default - the result is one entry per search, side by side. Pass `union: true` to merge them into a single ranked result set instead:
+
+```typescript
+await repository.dataSource.multiSearch({
+  searches: [
+    /* ... */
+  ],
+  union: true,
+});
+```
+
+Both `searches` entries and `commonParams` are camelCase (`filterBy`, `queryBy`, `perPage`); the datasource maps them to Typesense's snake_case wire format the same way single-collection `search()` does. For native snake_case access, `getConnector().multiSearch(...)` takes the engine's own params.
+
+> [!NOTE]
+> `multiSearch` injects each collection's `@model hiddenProperties` into that entry's `excludeFields` automatically - hidden fields never leak on the multi-search route, just as they don't on single-collection `search()`. An entry naming a collection IGNIS did not discover (not a bound `@repository` model) passes through untouched: the **caller owns exclusion** for unknown collections. The raw `getConnector().multiSearch(...)` escape hatch performs no injection at all.
+
+## Search Controller Factory
+
+`SearchControllerFactory.defineSearchController` generates turnkey search endpoints, mirroring how `ControllerFactory.defineCrudController` generates CRUD endpoints:
+
+```typescript
+// src/controllers/search.controller.ts
+import { ArticleDocument } from '@/models/entities';
+import { ArticleRepository } from '@/repositories';
+import { SearchControllerFactory } from '@venizia/ignis/typesense/controllers';
+
+const _SearchController = SearchControllerFactory.defineSearchController({
+  entity: ArticleDocument,
+  repository: { name: ArticleRepository.name },
+  controller: { name: 'ArticleSearchController', basePath: '/articles' },
+  // routes: { multiSearch: { enabled: false } },  // each route is customizable / disable-able
+});
+
+export const ArticleSearchController = _SearchController;
+```
+
+It registers `POST /search` (request body is the mode-discriminated schema, so validation and OpenAPI come for free and the handler dispatches to `repository.search`) and `POST /multi-search` (dispatches to `dataSource.multiSearch`). For anything the factory does not cover, write a custom `BaseRestController` calling `repository.search()` or `getClient()` directly.
+
+## Transactions and Locking
+
+The typesense connector has no transaction or row-level-locking model. Passing a `transaction` or `lock` option to any repository method throws:
+
+```typescript
+await articleRepository.updateById({
+  id: '123',
+  data: { title: 'New' },
+  options: { transaction: tx }, // throws: 501, messageCode 'core.not_supported'
+});
+```
+
+This is the same `throwNotSupported` convention used everywhere in the framework for capabilities an engine doesn't implement - see [Connectors](/references/base/connectors) and [Transactions](./transactions).
+
+## See Also
+
+- **Related Concepts:**
+  - [Connectors](/references/base/connectors) - Base-vs-connectors architecture, dual-door exports
+  - [DataSources](/references/base/datasources) - Engine-neutral DataSource contract + PostgreSQL connector
+  - [Repositories](/references/base/repositories/) - PostgreSQL connector repository reference (for comparison)
+  - [Models](./models) - `@model` settings shared across connectors
+
+- **Example App:**
+  - `examples/typesense-search/` - Full end-to-end app (model, datasource, repository, CRUD + search controllers, seed script)