nestjs-typesense 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ebenezer Domey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,318 @@
+# nestjs-typesense
+
+An unofficial NestJS module for [Typesense](https://typesense.org): typed collection schemas,
+declarative collection migrations, and **database-agnostic** index syncing.
+
+> Not affiliated with or endorsed by Typesense Inc. "Typesense" is their trademark.
+
+## Why
+
+The existing NestJS integrations either sync from MongoDB change streams — unusable if your
+data lives anywhere else — or pull an opinionated pagination and error envelope into your API
+responses. This module does neither. Indexing is expressed as ordinary queries against your own
+store, and nothing about your HTTP contract is dictated.
+
+## Install
+
+```bash
+npm i nestjs-typesense typesense
+```
+
+Peer dependencies: `@nestjs/common`, `@nestjs/core`, `reflect-metadata`, `typesense`.
+
+## Define a collection
+
+Field declarations drive both the Typesense schema and the TypeScript document type.
+
+```ts
+import { defineCollection, field } from 'nestjs-typesense'
+
+export const videoCollection = defineCollection({
+  name: 'videos',
+  fields: {
+    title: field.string(),
+    description: field.string({ optional: true }),
+    durationMs: field.int32({ sort: true }),
+    tags: field.stringArray({ facet: true }),
+    thumbnailUrl: field.string({ index: false, optional: true }),
+  },
+  defaultSortingField: 'durationMs',
+})
+```
+
+`InferDocument` gives you the document type, with `id` always present and `optional` fields
+genuinely optional:
+
+```ts
+import type { InferDocument } from 'nestjs-typesense'
+
+type VideoDocument = InferDocument<typeof videoCollection>
+// { id: string; title: string; durationMs: number; tags: string[]
+//   description?: string; thumbnailUrl?: string }
+```
+
+### Or declare it with decorators
+
+If you prefer the `@nestjs/mongoose` style, decorate a class instead. The class *is* the
+document type, so there is no `InferDocument` step:
+
+```ts
+import {
+  TypesenseArray,
+  TypesenseInt32,
+  TypesenseSchema,
+  TypesenseString,
+} from 'nestjs-typesense'
+
+@TypesenseSchema({ name: 'videos', defaultSortingField: 'durationMs' })
+export class VideoDocument {
+  @TypesenseString() title!: string
+  @TypesenseString({ optional: true }) description?: string
+  @TypesenseInt32({ sort: true }) durationMs!: number
+  @TypesenseArray({ type: 'string', facet: true }) tags!: string[]
+  @TypesenseString({ index: false, optional: true }) thumbnailUrl?: string
+}
+```
+
+Both forms produce the same collection, schema hash included, and either can be passed
+wherever a collection is expected.
+
+Unlike `@nestjs/mongoose`'s `@Prop()`, these decorators check the field against the property
+they annotate. Every one of these fails to compile:
+
+```ts
+@TypesenseInt32() title!: string                     // int32 on a string property
+@TypesenseString() thumbnailUrl?: string             // required field, optional property
+@TypesenseArray({ type: 'string' }) tags!: number[]  // element type disagrees
+@TypesenseArray({ type: 'string' }) tags!: string    // not an array at all
+@TypesenseArray({ type: 'typo' }) tags!: string[]    // not a field type
+```
+
+There is one decorator per scalar type — `TypesenseString`, `TypesenseInt32`,
+`TypesenseInt64`, `TypesenseFloat`, `TypesenseBool`, `TypesenseGeopoint`, `TypesenseObject`
+and `TypesenseAuto` — plus `TypesenseArray({ type })` covering all seven array types, and
+`TypesenseProp({ type })` if you would rather name the type explicitly.
+
+Modifiers stay inside the options object rather than stacking as separate decorators the way
+`class-validator` does with `@IsOptional()`. That is deliberate: `optional` has to travel in
+the same call as the type for TypeScript to check them against each other, and a stacked
+modifier is checked independently, so the type decorator could never see it.
+
+Fields declared on a base class are collected as well, so shared audit columns can live in
+one place. `id` is always implicit — declare `id: string` on the class if you want it in the
+document type and it will not be emitted twice.
+
+### Which style to use
+
+Both produce the same collection and are interchangeable everywhere downstream, so this is
+purely about how you like to declare things — with one hard constraint:
+
+|                                        | `defineCollection` | `@TypesenseSchema` |
+| -------------------------------------- | ------------------ | ------------------ |
+| TypeScript                             | yes                | yes                |
+| Plain JavaScript                       | yes                | no — decorator syntax needs a transpiler |
+| Requires `experimentalDecorators`      | no                 | yes                |
+| Document type                          | `InferDocument<typeof collection>` | the class itself |
+| Doubles as a DTO (`class-validator`, Swagger) | no          | yes                |
+
+NestJS projects already enable `experimentalDecorators` and `emitDecoratorMetadata`, so both
+styles work there without any config change. Reach for `defineCollection` if you are consuming
+this from plain JavaScript, from a non-Nest TypeScript project, or if you would rather keep
+schemas as plain data.
+
+The package ships CommonJS, so `require('nestjs-typesense')` works as-is.
+
+## Register the module
+
+```ts
+import { Module } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import { TypesenseModule } from 'nestjs-typesense'
+import { videoCollection } from './search/video.collection.js'
+
+@Module({
+  imports: [
+    TypesenseModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        nodes: [{ host: config.getOrThrow('TYPESENSE_HOST'), port: 8108, protocol: 'http' }],
+        apiKey: config.getOrThrow('TYPESENSE_API_KEY'),
+        connectionTimeoutSeconds: 5,
+        collections: [videoCollection],
+        migrations: 'alter',
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`collections` accepts either declaration style — `defineCollection()` results,
+`@TypesenseSchema()` classes, or a mix of both.
+
+### Migration strategies
+
+At bootstrap the module compares each declared collection against the live cluster.
+
+| Strategy   | Behaviour |
+| ---------- | --------- |
+| `off`      | Never touches the cluster. |
+| `create`   | Creates missing collections; logs a warning on drift. **Default.** |
+| `alter`    | Also adds new fields and drops removed ones in place. |
+| `recreate` | Drops and rebuilds on drift. **Destroys documents** — pair with a reindex. |
+
+Start on `create`, move to `alter` once you trust it. Every collection also carries a stable
+`hash` of its schema, computed independently of field declaration order.
+
+One Typesense constraint leaks through `alter`: a **required** field cannot be added to a
+collection that already holds documents, since the existing rows would have no value for
+it. Rather than failing the bootstrap, the module logs a warning naming the field and
+leaves the collection alone. Declare the field `optional: true`, or use `recreate` and
+reindex.
+
+## Sync from Postgres (or anything else)
+
+Implement a collector. There are no change streams — each method is just a query.
+
+```ts
+import { RegisterTypesenseCollector, type TypesenseCollector, type InferDocument } from 'nestjs-typesense'
+import { videoCollection } from './video.collection.js'
+
+const BATCH = 500
+
+@RegisterTypesenseCollector(videoCollection)
+export class VideoCollector implements TypesenseCollector<typeof videoCollection> {
+  constructor(private readonly repo: Repository<Video>) {}
+
+  transform(videos: Video[]): InferDocument<typeof videoCollection>[] {
+    return videos.map((v) => ({
+      id: v.id,
+      title: v.title,
+      durationMs: v.durationMs,
+      tags: v.tags,
+    }))
+  }
+
+  async *fetchAll(ids?: string[]) {
+    for (let skip = 0; ; skip += BATCH) {
+      const batch = await this.repo.find({
+        where: ids ? { id: In(ids) } : {},
+        order: { id: 'ASC' },
+        take: BATCH,
+        skip,
+      })
+      if (batch.length === 0) return
+      yield batch
+    }
+  }
+
+  async *fetchChanged(since: Date) {
+    yield await this.repo.find({ where: { updatedAt: MoreThan(since) } })
+  }
+
+  async *fetchRemoved(since: Date) {
+    const rows = await this.repo.find({ where: { deletedAt: MoreThan(since) }, withDeleted: true })
+    yield rows.map((r) => r.id)
+  }
+}
+```
+
+Register it as an ordinary provider — `@RegisterTypesenseCollector` applies `@Injectable()` for you.
+
+Then drive it from a cron job or CLI command:
+
+```ts
+constructor(private readonly indexer: TypesenseIndexer) {}
+
+await this.indexer.reindex(videoCollection)              // full rebuild
+await this.indexer.sync(videoCollection, lastRunAt)      // incremental
+await this.indexer.syncAll(lastRunAt)                    // every collection with a collector
+```
+
+## Search
+
+```ts
+constructor(private readonly typesense: TypesenseClient) {}
+
+const results = await this.typesense.search(videoCollection, {
+  q: 'mountain sunset',
+  query_by: 'title,description',
+  filter_by: 'durationMs:<60000',
+  per_page: 20,
+})
+
+results.hits[0].document.title // typed as string
+```
+
+`results` is a plain `{ found, page, hits, facets }` — shape your own API response from it.
+For anything not covered, `typesense.raw` is the official client.
+
+## Testing
+
+Unit tests cover schema inference and hashing and need nothing running:
+
+```bash
+npm test
+```
+
+The integration suite exercises the client, the bootstrap migrator and the indexer
+against a real Typesense server:
+
+```bash
+docker compose up -d          # or: brew services start typesense-server
+npm run test:integration
+```
+
+It refuses to run rather than skipping when no server answers, so a green run always
+means the server was hit. Point it elsewhere with `TYPESENSE_HOST`, `TYPESENSE_PORT`
+and `TYPESENSE_API_KEY`.
+
+It imports the built package rather than `src`, because vitest transpiles with esbuild,
+which honours `experimentalDecorators` but drops `emitDecoratorMetadata` — Nest cannot
+resolve constructor injection from source under that transform. `npm run
+test:integration` builds first.
+
+## Contributing
+
+Checks run at three points, each a superset of the one before.
+
+`bun install` installs [husky](https://typicode.github.io/husky/), which wires up two hooks:
+
+| Hook | Runs | Cost |
+| ---- | ---- | ---- |
+| `pre-commit` | `biome check` on staged files only | sub-second |
+| `pre-push` | build, typecheck, lint, format, unit tests | ~15s |
+
+CI then repeats the `pre-push` set across Node 20, 22 and 24, and additionally
+runs the integration suite against a real Typesense in Docker.
+
+`pre-push` deliberately stops short of the integration suite: that suite throws
+rather than skips when no server answers, so including it would block every push
+made while your local Typesense is down. Run it yourself with
+`npm run test:integration`. In a genuine emergency, `git push --no-verify`.
+
+One wrinkle worth knowing if you add checks: the typecheck needs `dist` to
+exist. `src/typesense.integration.test.ts` imports `../dist/index.js` by design,
+so `tsc --noEmit` fails on a clean checkout until you have built once. Both the
+hook and CI build first.
+
+## Status
+
+v0.1.0, CommonJS. ESM output can be added without a breaking change.
+
+Verified against Typesense 29/30: collection creation, the `create`/`alter`/`recreate`
+migration strategies, typed search with filtering, faceting and pagination, upsert and
+delete, and full plus incremental indexing through collectors.
+
+Known rough edges:
+
+- `query_by`, `filter_by`, `sort_by` and `facet_by` are unchecked strings; a typo fails
+  at runtime, not at compile time.
+- A collection reached through `resolveCollection()` or `TypesenseCollections.get()`
+  loses its field types, so `search` returns loosely typed documents. Import the
+  `defineCollection()` result directly to keep them.
+- No multi-search, and no point lookup by id — drop to `client.raw` for both.
+
+## License
+
+MIT © Ebenezer Domey

package/dist/client/typesense.client.d.ts

@@ -0,0 +1,38 @@
+import { Client } from "typesense";
+import type { InferDocument, TypesenseCollection } from "../schema/collection.js";
+import type { TypesenseModuleOptions } from "../typesense.module-options.js";
+export interface SearchParams {
+    q: string;
+    query_by: string;
+    filter_by?: string;
+    sort_by?: string;
+    facet_by?: string;
+    page?: number;
+    per_page?: number;
+    [key: string]: unknown;
+}
+export interface SearchResult<TDocument> {
+    found: number;
+    page: number;
+    hits: {
+        document: TDocument;
+        highlights?: unknown[];
+    }[];
+    facets?: unknown[];
+}
+/**
+ * Thin wrapper over the official Typesense client, typed against collection definitions.
+ * Deliberately does not impose a pagination or error envelope — callers keep their own.
+ */
+export declare class TypesenseClient {
+    private readonly options;
+    private readonly logger;
+    readonly raw: Client;
+    constructor(options: TypesenseModuleOptions);
+    search<TCollection extends TypesenseCollection>(collection: TCollection, params: SearchParams): Promise<SearchResult<InferDocument<TCollection>>>;
+    upsert<TCollection extends TypesenseCollection>(collection: TCollection, documents: InferDocument<TCollection>[]): Promise<void>;
+    private reportImportFailures;
+    delete(collection: TypesenseCollection, ids: string[]): Promise<void>;
+    private handleError;
+}
+//# sourceMappingURL=typesense.client.d.ts.map

package/dist/client/typesense.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesense.client.d.ts","sourceRoot":"","sources":["../../src/client/typesense.client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAElF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAQD,MAAM,WAAW,YAAY,CAAC,SAAS;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QAAE,QAAQ,EAAE,SAAS,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,EAAE,CAAC;IACxD,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,qBACa,eAAe;IAIoB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAE0C,OAAO,EAAE,sBAAsB;IAKxF,MAAM,CAAC,WAAW,SAAS,mBAAmB,EAClD,UAAU,EAAE,WAAW,EACvB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAc9C,MAAM,CAAC,WAAW,SAAS,mBAAmB,EAClD,UAAU,EAAE,WAAW,EACvB,SAAS,EAAE,aAAa,CAAC,WAAW,CAAC,EAAE,GACtC,OAAO,CAAC,IAAI,CAAC;IAqBhB,OAAO,CAAC,oBAAoB;IAWtB,MAAM,CAAC,UAAU,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAe3E,OAAO,CAAC,WAAW;CAOpB"}

package/dist/client/typesense.client.js

@@ -0,0 +1,100 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var TypesenseClient_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypesenseClient = void 0;
+const common_1 = require("@nestjs/common");
+const typesense_1 = require("typesense");
+const typesense_constants_js_1 = require("../typesense.constants.js");
+/**
+ * Thin wrapper over the official Typesense client, typed against collection definitions.
+ * Deliberately does not impose a pagination or error envelope — callers keep their own.
+ */
+let TypesenseClient = TypesenseClient_1 = class TypesenseClient {
+    options;
+    logger = new common_1.Logger(TypesenseClient_1.name);
+    raw;
+    constructor(options) {
+        this.options = options;
+        const { collections: _c, migrations: _m, onError: _e, ...config } = options;
+        this.raw = new typesense_1.Client(config);
+    }
+    async search(collection, params) {
+        const result = await this.raw
+            .collections(collection.name)
+            .documents()
+            .search(params);
+        return {
+            found: result.found,
+            page: result.page,
+            hits: (result.hits ?? []),
+            ...(result.facet_counts ? { facets: result.facet_counts } : {}),
+        };
+    }
+    async upsert(collection, documents) {
+        if (documents.length === 0)
+            return;
+        // typesense-js throws `ImportError` when any document is rejected rather than
+        // returning the per-document results, so the failure path lives in the catch.
+        // Transport errors carry no `importResults` and are rethrown — only per-document
+        // rejections are routed through `onError`.
+        try {
+            const results = await this.raw
+                .collections(collection.name)
+                .documents()
+                .import(documents, { action: "upsert" });
+            this.reportImportFailures(results, documents.length, collection.name);
+        }
+        catch (error) {
+            const results = error.importResults;
+            if (!results)
+                throw error;
+            this.reportImportFailures(results, documents.length, collection.name);
+        }
+    }
+    reportImportFailures(results, total, name) {
+        const failures = results.filter((r) => !r.success);
+        if (failures.length === 0)
+            return;
+        this.handleError(new Error(`${failures.length}/${total} documents failed to index into "${name}": ${failures[0]?.error}`));
+    }
+    async delete(collection, ids) {
+        if (ids.length === 0)
+            return;
+        await Promise.all(ids.map(async (id) => {
+            try {
+                await this.raw.collections(collection.name).documents(id).delete();
+            }
+            catch (error) {
+                // A document already gone is not a failure — the desired end state holds.
+                if (error.httpStatus !== 404)
+                    this.handleError(error);
+            }
+        }));
+    }
+    handleError(error) {
+        if (this.options.onError) {
+            this.options.onError(error);
+            return;
+        }
+        this.logger.error(error instanceof Error ? error.message : String(error));
+    }
+};
+exports.TypesenseClient = TypesenseClient;
+exports.TypesenseClient = TypesenseClient = TypesenseClient_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(typesense_constants_js_1.TYPESENSE_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], TypesenseClient);
+//# sourceMappingURL=typesense.client.js.map

package/dist/client/typesense.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesense.client.js","sourceRoot":"","sources":["../../src/client/typesense.client.ts"],"names":[],"mappings":"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"}

package/dist/collections/typesense-collections.d.ts

@@ -0,0 +1,21 @@
+import { type OnApplicationBootstrap } from "@nestjs/common";
+import { TypesenseClient } from "../client/typesense.client.js";
+import { type TypesenseCollection } from "../schema/collection.js";
+import type { TypesenseModuleOptions } from "../typesense.module-options.js";
+/**
+ * Reconciles declared collections with the live Typesense cluster at bootstrap,
+ * according to the configured migration strategy.
+ */
+export declare class TypesenseCollections implements OnApplicationBootstrap {
+    private readonly options;
+    private readonly client;
+    private readonly logger;
+    private readonly byName;
+    constructor(options: TypesenseModuleOptions, client: TypesenseClient);
+    get(name: string): TypesenseCollection;
+    all(): TypesenseCollection[];
+    onApplicationBootstrap(): Promise<void>;
+    private reconcile;
+    private retrieve;
+}
+//# sourceMappingURL=typesense-collections.d.ts.map

package/dist/collections/typesense-collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesense-collections.d.ts","sourceRoot":"","sources":["../../src/collections/typesense-collections.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,KAAK,mBAAmB,EAAY,MAAM,yBAAyB,CAAC;AAG7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAE7E;;;GAGG;AACH,qBACa,oBAAqB,YAAW,sBAAsB;IAK7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;gBAGZ,OAAO,EAAE,sBAAsB,EACjE,MAAM,EAAE,eAAe;IAQ1C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB;IAMtC,GAAG,IAAI,mBAAmB,EAAE;IAItB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;YAS/B,SAAS;YAiET,QAAQ;CAQvB"}

package/dist/collections/typesense-collections.js

@@ -0,0 +1,120 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var TypesenseCollections_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypesenseCollections = void 0;
+const common_1 = require("@nestjs/common");
+const typesense_client_js_1 = require("../client/typesense.client.js");
+const collection_js_1 = require("../schema/collection.js");
+const decorators_js_1 = require("../schema/decorators.js");
+const typesense_constants_js_1 = require("../typesense.constants.js");
+/**
+ * Reconciles declared collections with the live Typesense cluster at bootstrap,
+ * according to the configured migration strategy.
+ */
+let TypesenseCollections = TypesenseCollections_1 = class TypesenseCollections {
+    options;
+    client;
+    logger = new common_1.Logger(TypesenseCollections_1.name);
+    byName = new Map();
+    constructor(options, client) {
+        this.options = options;
+        this.client = client;
+        for (const source of options.collections ?? []) {
+            const collection = (0, decorators_js_1.resolveCollection)(source);
+            this.byName.set(collection.name, collection);
+        }
+    }
+    get(name) {
+        const collection = this.byName.get(name);
+        if (!collection)
+            throw new Error(`Typesense collection "${name}" is not registered`);
+        return collection;
+    }
+    all() {
+        return [...this.byName.values()];
+    }
+    async onApplicationBootstrap() {
+        const strategy = this.options.migrations ?? "create";
+        if (strategy === "off")
+            return;
+        for (const collection of this.byName.values()) {
+            await this.reconcile(collection, strategy);
+        }
+    }
+    async reconcile(collection, strategy) {
+        const schema = (0, collection_js_1.toSchema)(collection);
+        const live = await this.retrieve(collection.name);
+        if (!live) {
+            await this.client.raw.collections().create(schema);
+            this.logger.log(`Created collection "${collection.name}" (${collection.hash})`);
+            return;
+        }
+        const liveNames = new Set((live.fields ?? []).map((f) => f.name));
+        const declaredNames = new Set(schema.fields.map((f) => f.name));
+        // `id` is implicit in Typesense: `toSchema` emits it, but `retrieve()` never lists it
+        // and `update()` rejects it outright ("Field `id` cannot be altered"). Skip it on both
+        // sides of the diff or every alter of a drifted collection fails with a 400.
+        const added = schema.fields.filter((f) => f.name !== "id" && !liveNames.has(f.name));
+        const removed = [...liveNames].filter((n) => n !== "id" && !declaredNames.has(n));
+        if (added.length === 0 && removed.length === 0)
+            return;
+        const drift = `+${added.length} -${removed.length} field(s)`;
+        if (strategy === "create") {
+            this.logger.warn(`Collection "${collection.name}" has drifted (${drift}). Strategy is "create" — not altering. Set migrations: "alter" to apply.`);
+            return;
+        }
+        if (strategy === "recreate") {
+            await this.client.raw.collections(collection.name).delete();
+            await this.client.raw.collections().create(schema);
+            this.logger.warn(`Recreated collection "${collection.name}" (${drift}). Documents dropped — reindex required.`);
+            return;
+        }
+        // Typesense refuses to add a required field to a collection that already holds
+        // documents — the existing rows would have no value for it. Catch it here so the
+        // failure names the fix instead of surfacing as a bare 400 during bootstrap.
+        const documents = live.num_documents ?? 0;
+        const required = added.filter((f) => !f.optional).map((f) => f.name);
+        if (documents > 0 && required.length > 0) {
+            // Warn and skip rather than throw, matching the "create" branch above: unappliable
+            // drift should not take an app down at bootstrap.
+            this.logger.warn(`Collection "${collection.name}" not altered: ${required.join(", ")} ` +
+                `${required.length === 1 ? "is" : "are"} required, and the collection already holds ` +
+                `${documents} document(s) with no value for ${required.length === 1 ? "it" : "them"}. ` +
+                'Declare the field optional, or use migrations: "recreate" and reindex.');
+            return;
+        }
+        await this.client.raw.collections(collection.name).update({
+            fields: [...removed.map((name) => ({ name, drop: true })), ...added],
+        });
+        this.logger.log(`Altered collection "${collection.name}" (${drift})`);
+    }
+    async retrieve(name) {
+        try {
+            return await this.client.raw.collections(name).retrieve();
+        }
+        catch (error) {
+            if (error.httpStatus === 404)
+                return undefined;
+            throw error;
+        }
+    }
+};
+exports.TypesenseCollections = TypesenseCollections;
+exports.TypesenseCollections = TypesenseCollections = TypesenseCollections_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(typesense_constants_js_1.TYPESENSE_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object, typesense_client_js_1.TypesenseClient])
+], TypesenseCollections);
+//# sourceMappingURL=typesense-collections.js.map

package/dist/collections/typesense-collections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesense-collections.js","sourceRoot":"","sources":["../../src/collections/typesense-collections.ts"],"names":[],"mappings":"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"}

package/dist/collectors/typesense-collector.d.ts

@@ -0,0 +1,22 @@
+import type { InferDocument, TypesenseCollection } from "../schema/collection.js";
+/**
+ * Feeds documents into a collection.
+ *
+ * This is deliberately pull-based rather than driven by database change events, so it
+ * works over any store. With Postgres each method is an ordinary query — `fetchChanged`
+ * is a `WHERE updated_at > $1`, `fetchRemoved` reads your soft-delete or tombstone table.
+ *
+ * Every method yields batches so a full reindex streams instead of loading the table
+ * into memory.
+ */
+export interface TypesenseCollector<TCollection extends TypesenseCollection = TypesenseCollection> {
+    /** Map a batch of source rows to Typesense documents. */
+    transform(entities: unknown[]): InferDocument<TCollection>[];
+    /** Every row, for a full rebuild. Optionally narrowed to specific ids. */
+    fetchAll(ids?: string[]): AsyncGenerator<unknown[], void, void>;
+    /** Rows created or updated since `since`, for an incremental pass. */
+    fetchChanged(since: Date): AsyncGenerator<unknown[], void, void>;
+    /** Ids deleted since `since`. Omit if the source never hard-deletes. */
+    fetchRemoved?(since: Date): AsyncGenerator<string[], void, void>;
+}
+//# sourceMappingURL=typesense-collector.d.ts.map