@nxgt/mongo-meilisearch 0.1.8 → 0.3.0

package/README.md

@@ -120,7 +120,8 @@ it: deleted, turned away by the transform, or never from this collection.
 It first records where the collection's changes are, and saves that point
 when it is done: a change made while it reads is followed again from there,
 so none falls between the reindex and the stream. A reindex that fails
-records nothing.
+records nothing, and one that finds its lease taken over stops before it
+removes anything more (see *One process per sync name*).
 
 ## Following changes
 
@@ -155,6 +156,59 @@ await running.close(); // flushes, then stops; or `await using running = …`
   resume from inside a collection that no longer exists. The next `start`
   reindexes what the recreated collection holds.
 
+### One process per sync name
+
+`start` takes a **lease** on the sync's name before anything else, the first
+reindex included, and a running sync renews it every third of `leaseMs`
+(30 s). A second process that starts the same name is refused with
+`RUNNING`, naming who holds it and until when. Run it as a standby that
+tries again — on `RUNNING`, and on `LEASE_LOST`, which a `start()` whose
+first reindex lost the name to another process rejects with:
+
+```ts
+import { type RunningSearchSync, SearchSyncError } from '@nxgt/mongo-meilisearch';
+
+// The name is held elsewhere, or was taken over while this start reindexed.
+const heldElsewhere = (error: unknown) =>
+	error instanceof SearchSyncError &&
+	(error.code === 'RUNNING' || error.code === 'LEASE_LOST');
+
+async function follow(): Promise<RunningSearchSync> {
+	for (;;) {
+		try {
+			return await articleSearch.start();
+		} catch (error) {
+			if (!heldElsewhere(error)) throw error;
+			await new Promise((resolve) => setTimeout(resolve, 10_000));
+		}
+	}
+}
+```
+
+A restart inside a crashed follower's `leaseMs` gets `RUNNING` too: run this
+loop rather than exit.
+
+- **`close()` lets go of the name**, and resolves once it has: a `start` or a
+  `reindex` right after finds it free. A `start` that fails lets go too.
+- **A process that dies keeps the name** until its lease lapses, at most
+  `leaseMs` later; the next `start` then takes it over.
+- **`reindex()` on its own takes the lease** for as long as it runs, so it
+  cannot run beside a follower in another process. `start()` renews it
+  during its first reindex too.
+- **A sync that loses its lease stops.** When a renewal finds the name held
+  by someone else — this process stalled for longer than `leaseMs`, and
+  another took over — `closed` rejects with `LEASE_LOST`, and nothing more is
+  sent.
+- **A reindex that loses its lease stops too.** `reindex()`, and `start()`
+  while it reindexes, check the lease after each page, and ask the server
+  before removing documents and again before recording the resume point;
+  `start()` asks once more before it opens the follower. They reject with
+  `LEASE_LOST` having recorded nothing, and removed nothing unless the lease
+  went while the removal itself ran; the pages already sent stay in the index.
+
+The lease is a document in `stateCollection`, `_id: { lease: <name> }`, its
+times the server's own: no new collection and no new privilege.
+
 ### When the history is gone
 
 MongoDB keeps a bounded history of changes, the oplog. A sync stopped for
@@ -192,7 +246,8 @@ createSearchSync({
 
 The transform must give each document its index id as primary key: a
 document under another id could never be taken out again, and throws
-`ID_MISMATCH`.
+`ID_MISMATCH`. It must also give back a document, or `null` to keep the
+document out of the index; anything else is `NOT_A_DOCUMENT`.
 
 ## Errors
 
@@ -202,7 +257,9 @@ This package throws `SearchSyncError`; what caused it is its `cause`.
 | --- | --- |
 | `HISTORY_LOST` | `start` with `onHistoryLost: 'fail'`, and the recorded point is older than the server's history. `cause` is `@nxgt/mongo`'s `DataError`, `serverCode` 286 or 280 |
 | `ID_MISMATCH` | the transform gave a document whose primary key is not its index id |
-| `RUNNING` | `reindex()` or a second `start()` while this sync is already following changes in this process. A reindex beside its own follower would remove what the follower has just indexed |
+| `NOT_A_DOCUMENT` | the transform gave back something that is neither a document nor `null` — a string, a number, an array. The message says its shape, never its value |
+| `RUNNING` | the name is taken. On this sync object: `reindex()` or a second `start()` while it is already following. Through the lease: `start()` or `reindex()` while another process holds the name — or another `createSearchSync` with the same name in this process, whose holder then starts with this process's own `host:pid`. The message names the holder and when its lease ends |
+| `LEASE_LOST` | the name's lease is no longer this sync's: it was not renewed within `leaseMs` and another process took it over, or it was removed. `closed` rejects with it, and nothing more is sent; `reindex()` and `start()` reject with it while reindexing, having recorded nothing, and removed nothing unless the lease went while the removal itself ran |
 | `FAILED` | anything else: the transform threw, MongoDB or Meilisearch refused. The message says what the sync was doing |
 
 A running sync that meets one stops: `closed` rejects with it, and `flush`
@@ -225,11 +282,11 @@ out of range, an empty `name`, or a `transform` that is not a function.
 
 ## Not included
 
-- **Several processes sharing one sync — not yet.** There is no lock today,
-  so run **one** follower per sync name. Two do the same writes twice, and a
-  `reindex` in one while the other follows removes documents the follower has
-  already indexed and will not send again. A lease on a sync name is being
-  worked on: [the roadmap](docs/roadmap.md) says where it stands.
+- **Sharing one name's work between processes.** One process follows a
+  name at a time; the others wait for its lease. To spread the load, give
+  each process its own collection and name.
+- **Fencing.** The lease keeps a second process out, but does not stop a
+  stalled one mid-write; see *Traps*.
 - **Partial updates.** A change sends the whole document the transform
   gives, never a patch.
 - **Keeping the index's settings.** That is `@nxgt/meilisearch`'s `sync`.
@@ -259,6 +316,7 @@ function createSearchSync<C extends AnyCollectionDefinition, I extends AnyIndexD
 | `batchSize: number` | `500` | changes sent at once |
 | `flushIntervalMs: number` | `1000` | how long a change waits for others; `0` sends at the next tick |
 | `positionIntervalMs: number` | `60000` | how often a sync with nothing to send records where the stream is |
+| `leaseMs: number` | `30000` | how long the lease on the name lasts unrenewed; a running sync renews it every third of that |
 | `pageSize: number` | `100` | documents a reindex reads per page; above the collection's `maxPageSize`, lowered to it |
 | `onHistoryLost: 'reindex' \| 'fail'` | `'reindex'` | |
 
@@ -281,7 +339,8 @@ function createSearchSync<C extends AnyCollectionDefinition, I extends AnyIndexD
 | `close(): Promise<void>` | flushes, then stops |
 
 `class SearchSyncError extends Error`: `code: SearchSyncErrorCode`
-(`'HISTORY_LOST' | 'ID_MISMATCH' | 'RUNNING' | 'FAILED'`), `sync: string`,
+(`'HISTORY_LOST' | 'ID_MISMATCH' | 'NOT_A_DOCUMENT' | 'RUNNING' | 'LEASE_LOST' | 'FAILED'`),
+`sync: string`,
 `cause`. Its constructor takes `(message, options: SearchSyncErrorOptions)`,
 that is `{ code, sync, cause? }`; both types are exported.
 
@@ -320,10 +379,16 @@ Each is a `@ts-expect-error` case in this package's type tests.
 - **Without post-images, a change carries the document as it is now**, not
   as the change left it (`@nxgt/mongo`'s change streams). For an index, where
   only the latest state counts, that is what you want.
-- **Only one process per sync name**, while there is no lock; see *Not
-  included*. Inside one process this package refuses it: `reindex()` and a
-  second `start()` throw `RUNNING` while a sync of the same object is
-  following.
+- **A lease is not fencing.** A stalled process learns it lost the name at
+  its next renewal (up to `leaseMs / 3` after it wakes), and a flush already
+  in flight still finishes. It may send an older version of a document after
+  the new holder sent a newer one; the index then holds the stale one until
+  that document's next change or the next reindex. A reindex removes and
+  records nothing once it finds its lease lost, but a page it already sent may
+  still land. Keep `leaseMs` well above the longest pause a process may take
+  (garbage collection, a blocked event loop).
+- **Two syncs over the same collection and index share a name**, and so a
+  lease: give them different `name`s when both are meant to run.
 - **A dropped collection stops the sync** (`'invalidated'`) and leaves the
   index as it was. What the collection had is removed by the reindex the
   next `start` runs.
@@ -347,7 +412,7 @@ Each is a `@ts-expect-error` case in this package's type tests.
 - [Following changes](docs/guide/following-changes.md) — batches, the resume
   point, and how a sync stops.
 - [What it leaves out](docs/guide/boundaries.md) — the settings, the joins,
-  and the one follower per sync name.
+  and the lease that keeps one follower per sync name.
 - [Troubleshooting](docs/troubleshooting.md) — the errors, by their message.
 - [Roadmap](docs/roadmap.md) — what is next, and what is not planned.
 

package/dist/context.d.ts

@@ -1,6 +1,7 @@
 import type { AnyIndexDefinition, TypedIndex } from '@nxgt/meilisearch';
 import type { AnyCollectionDefinition, TypedCollection } from '@nxgt/mongo';
 import type { Collection } from 'mongodb';
+import type { LeaseDocument } from './lease';
 import type { SearchSyncOptions, SearchSyncState } from './types';
 /** Loosely typed: this layer works on any documents; the public types are what callers see. */
 export type Doc = Record<string, unknown>;
@@ -14,6 +15,10 @@ export interface SyncContext {
     readonly index: TypedIndex<AnyIndexDefinition>;
     readonly primaryKey: string;
     readonly state: Collection<SearchSyncState>;
+    /** The same collection, for the lease documents it also holds. */
+    readonly leases: Collection<LeaseDocument>;
+    /** How long a lease lasts unrenewed, in ms. */
+    readonly leaseMs: number;
     readonly batchSize: number;
     readonly flushIntervalMs: number;
     readonly positionIntervalMs: number;

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAElE,+FAA+F;AAC/F,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,uBAAuB,CAAC,CAAC;IAC9D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACxC;AAcD,wBAAgB,aAAa,CAC5B,OAAO,EAAE,iBAAiB,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,GACrE,WAAW,CAoCb"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAElE,+FAA+F;AAC/F,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,uBAAuB,CAAC,CAAC;IAC9D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC5C,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IAC3C,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACxC;AAcD,wBAAgB,aAAa,CAC5B,OAAO,EAAE,iBAAiB,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,GACrE,WAAW,CAqCb"}

package/dist/documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGlD,4DAA4D;AAC5D,MAAM,MAAM,KAAK,GACd;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,sEAAsE;AACtE,eAAO,MAAM,KAAK,GAAI,IAAI,OAAO,WAAiC,CAAC;AAKnE;;;GAGG;AACH,wBAAsB,OAAO,CAC5B,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,GAAG,GAAG,SAAS,GACvB,OAAO,CAAC,KAAK,CAAC,CAsBhB"}
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGlD,4DAA4D;AAC5D,MAAM,MAAM,KAAK,GACd;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,sEAAsE;AACtE,eAAO,MAAM,KAAK,GAAI,IAAI,OAAO,WAAiC,CAAC;AAYnE;;;GAGG;AACH,wBAAsB,OAAO,CAC5B,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,GAAG,GAAG,SAAS,GACvB,OAAO,CAAC,KAAK,CAAC,CA6BhB"}

package/dist/errors.d.ts

@@ -4,8 +4,18 @@ export type SearchSyncErrorCode =
 'HISTORY_LOST'
 /** The transform gave a document whose primary key is not its index id. */
  | 'ID_MISMATCH'
-/** This sync is already following changes in this process. */
+/** The transform gave something that is neither a document nor `null`. */
+ | 'NOT_A_DOCUMENT'
+/**
+ * This sync's name is taken: it is following changes in this process, or
+ * another process holds its lease.
+ */
  | 'RUNNING'
+/**
+ * A running sync's lease was not renewed in time and is no longer its
+ * own: it stopped rather than follow beside whoever took the name over.
+ */
+ | 'LEASE_LOST'
 /** Anything else: the cause says what. */
  | 'FAILED';
 export interface SearchSyncErrorOptions {

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,MAAM,mBAAmB;AAC9B,kEAAkE;AAChE,cAAc;AAChB,2EAA2E;GACzE,aAAa;AACf,8DAA8D;GAC5D,SAAS;AACX,0CAA0C;GACxC,QAAQ,CAAC;AAEZ,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,mEAAmE;AACnE,qBAAa,eAAgB,SAAQ,KAAK;IAChC,IAAI,SAAqB;IAClC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB;CAQ5D;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,mBAWjE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,MAAM,mBAAmB;AAC9B,kEAAkE;AAChE,cAAc;AAChB,2EAA2E;GACzE,aAAa;AACf,0EAA0E;GACxE,gBAAgB;AAClB;;;GAGG;GACD,SAAS;AACX;;;GAGG;GACD,YAAY;AACd,0CAA0C;GACxC,QAAQ,CAAC;AAEZ,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,mEAAmE;AACnE,qBAAa,eAAgB,SAAQ,KAAK;IAChC,IAAI,SAAqB;IAClC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB;CAQ5D;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,mBAWjE"}

package/dist/follow.d.ts

@@ -1,9 +1,6 @@
+import type { ResumeToken } from '@nxgt/mongo';
 import type { SyncContext } from './context';
+import { type HeldLease } from './lease';
 import type { RunningSearchSync } from './types';
-/**
- * Follows the collection from its recorded point — after a reindex when
- * nothing is recorded, or when the point is older than the server's history
- * and `onHistoryLost` allows it.
- */
-export declare function start(ctx: SyncContext): Promise<RunningSearchSync>;
+export declare function open(ctx: SyncContext, token: ResumeToken, lease: HeldLease): Promise<RunningSearchSync>;
 //# sourceMappingURL=follow.d.ts.map

package/dist/follow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"follow.d.ts","sourceRoot":"","sources":["../src/follow.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAO,WAAW,EAAE,MAAM,WAAW,CAAC;AAMlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAyJjD;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2BxE"}
+{"version":3,"file":"follow.d.ts","sourceRoot":"","sources":["../src/follow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKX,WAAW,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAO,WAAW,EAAE,MAAM,WAAW,CAAC;AAGlD,OAAO,EAAE,KAAK,SAAS,EAAiC,MAAM,SAAS,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AA+HjD,wBAAsB,IAAI,CACzB,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GACd,OAAO,CAAC,iBAAiB,CAAC,CAkE5B"}

package/dist/index.js

@@ -20,12 +20,15 @@ function createContext(options) {
   if (!Number.isInteger(flushIntervalMs) || flushIntervalMs < 0) {
     throw new TypeError(`createSearchSync: flushIntervalMs must be a whole number of milliseconds, not ${String(options.flushIntervalMs)}`);
   }
+  const stateCollection = options.stateCollection ?? DEFAULT_STATE_COLLECTION;
   return {
     name,
     collection,
     index,
     primaryKey: index.definition.primaryKey,
-    state: collection.db.collection(options.stateCollection ?? DEFAULT_STATE_COLLECTION),
+    state: collection.db.collection(stateCollection),
+    leases: collection.db.collection(stateCollection),
+    leaseMs: positive("leaseMs", options.leaseMs, 30000),
     batchSize: positive("batchSize", options.batchSize, 500),
     positionIntervalMs: positive("positionIntervalMs", options.positionIntervalMs, 60000),
     flushIntervalMs,
@@ -37,6 +40,9 @@ function createContext(options) {
   };
 }
 
+// src/reindex.ts
+import { MeilisearchApiError } from "meilisearch";
+
 // src/batch.ts
 var WAIT = { wait: { timeout: 120000 } };
 function chunks(items, size) {
@@ -92,6 +98,13 @@ function failed(sync, doing, error) {
 // src/documents.ts
 var keyOf = (id) => `${typeof id}:${String(id)}`;
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function describe(value) {
+  if (Array.isArray(value))
+    return "an array";
+  if (value === undefined)
+    return "undefined";
+  return `a ${typeof value}`;
+}
 async function entryOf(ctx, mongoId, document) {
   const id = ctx.toIndexId(mongoId);
   const key = keyOf(id);
@@ -101,7 +114,7 @@ async function entryOf(ctx, mongoId, document) {
   if (indexed === null)
     return { kind: "delete", key, id };
   if (!isRecord(indexed)) {
-    throw new TypeError(`transform must return a document or null, not ${String(indexed)}`);
+    throw new SearchSyncError(`Search sync "${ctx.name}": transform gave ${describe(indexed)} for ` + `the document ${String(mongoId)}. It must give a document to ` + "index, or null to keep it out.", { code: "NOT_A_DOCUMENT", sync: ctx.name });
   }
   const given = indexed[ctx.primaryKey];
   if (keyOf(given) !== key) {
@@ -110,8 +123,108 @@ async function entryOf(ctx, mongoId, document) {
   return { kind: "upsert", key, document: indexed };
 }
 
-// src/reindex.ts
-import { MeilisearchApiError } from "meilisearch";
+// src/lease.ts
+import { hostname } from "node:os";
+import { ObjectId } from "mongodb";
+var idOf = (ctx) => ({ lease: ctx.name });
+async function take(ctx, holder) {
+  const free = {
+    $or: [
+      { $eq: [{ $type: "$expiresAt" }, "missing"] },
+      { $lte: ["$expiresAt", "$$NOW"] }
+    ]
+  };
+  const pick = (mine, theirs) => ({
+    $cond: [free, mine, theirs]
+  });
+  try {
+    const after = await ctx.leases.findOneAndUpdate({ _id: idOf(ctx) }, [
+      {
+        $set: {
+          holder: pick({ $literal: holder }, "$holder"),
+          acquiredAt: pick("$$NOW", "$acquiredAt"),
+          expiresAt: pick({ $add: ["$$NOW", ctx.leaseMs] }, "$expiresAt")
+        }
+      }
+    ], { upsert: true, returnDocument: "after" });
+    return after?.holder === holder;
+  } catch (error) {
+    if (error.code === 11000)
+      return false;
+    throw error;
+  }
+}
+async function acquire(ctx, doing) {
+  const holder = `${hostname()}:${process.pid}:${new ObjectId().toHexString()}`;
+  let current = null;
+  try {
+    for (let attempt = 0;attempt < 2; attempt += 1) {
+      if (await take(ctx, holder))
+        return { holder, lost: false };
+      current = await ctx.leases.findOne({ _id: idOf(ctx) });
+      if (current)
+        break;
+    }
+  } catch (error) {
+    throw failed(ctx.name, "taking its lease", error);
+  }
+  const until = current?.expiresAt instanceof Date ? current.expiresAt.toISOString() : "it lets go";
+  throw new SearchSyncError(`Search sync "${ctx.name}" is held by ${current?.holder ?? "another process"} ` + `until ${until}: ` + `wait for it to close, or for its lease to lapse, before you ${doing}.`, { code: "RUNNING", sync: ctx.name });
+}
+async function renew(ctx, lease) {
+  try {
+    const result = await ctx.leases.updateOne({ _id: idOf(ctx), holder: lease.holder }, [{ $set: { expiresAt: { $add: ["$$NOW", ctx.leaseMs] } } }]);
+    if (result.matchedCount === 0)
+      lease.lost = true;
+  } catch {}
+}
+async function confirmLease(ctx, lease) {
+  let result;
+  try {
+    result = await ctx.leases.updateOne({ _id: idOf(ctx), holder: lease.holder }, [{ $set: { expiresAt: { $add: ["$$NOW", ctx.leaseMs] } } }]);
+  } catch (error) {
+    throw failed(ctx.name, "checking its lease", error);
+  }
+  if (result.matchedCount === 0)
+    lease.lost = true;
+  if (lease.lost)
+    throw leaseLost(ctx);
+}
+async function release(ctx, lease) {
+  await ctx.leases.deleteOne({ _id: idOf(ctx), holder: lease.holder }).catch(() => {
+    return;
+  });
+}
+function leaseLost(ctx) {
+  return new SearchSyncError(`Search sync "${ctx.name}" lost its lease: another process holds the ` + "name now, or the lease was removed (it lapses when not renewed " + `within ${ctx.leaseMs} ms). It stopped rather than run beside it.`, { code: "LEASE_LOST", sync: ctx.name });
+}
+function keepLease(ctx, lease, onLost) {
+  let stopped = false;
+  const beat = setInterval(() => {
+    renew(ctx, lease).then(() => {
+      if (lease.lost && !stopped) {
+        clearInterval(beat);
+        onLost();
+      }
+    });
+  }, Math.max(1, Math.floor(ctx.leaseMs / 3)));
+  return () => {
+    stopped = true;
+    clearInterval(beat);
+  };
+}
+async function withLease(ctx, doing, fn) {
+  const lease = await acquire(ctx, doing);
+  const stop = keepLease(ctx, lease, () => {
+    return;
+  });
+  try {
+    return await fn(lease);
+  } finally {
+    stop();
+    await release(ctx, lease);
+  }
+}
 
 // src/running.ts
 function checkIdle(ctx, doing) {
@@ -160,7 +273,7 @@ async function currentToken(ctx) {
     await stream.close();
   }
 }
-async function sendAll(ctx, wanted) {
+async function sendAll(ctx, wanted, lease) {
   let indexed = 0;
   let skipped = 0;
   let after;
@@ -181,6 +294,8 @@ async function sendAll(ctx, wanted) {
     }
     await sendDocuments(ctx, documents);
     indexed += documents.length;
+    if (lease.lost)
+      throw leaseLost(ctx);
     after = page.nextCursor;
   } while (after);
   return { indexed, skipped };
@@ -210,11 +325,16 @@ async function removeUnwanted(ctx, wanted) {
 }
 async function reindex(ctx) {
   checkIdle(ctx, "reindex");
+  return withLease(ctx, "reindex", (lease) => reindexHeld(ctx, lease));
+}
+async function reindexHeld(ctx, lease) {
   try {
     const token = await currentToken(ctx);
     const wanted = new Set;
-    const { indexed, skipped } = await sendAll(ctx, wanted);
+    const { indexed, skipped } = await sendAll(ctx, wanted, lease);
+    await confirmLease(ctx, lease);
     const removed = await removeUnwanted(ctx, wanted);
+    await confirmLease(ctx, lease);
     await saveState(ctx, token, true);
     return { indexed, skipped, removed };
   } catch (error) {
@@ -223,10 +343,9 @@ async function reindex(ctx) {
 }
 
 // src/follow.ts
-function historyLost(error) {
-  const code = error?.serverCode;
-  return code === 286 || code === 280;
-}
+var noop = () => {
+  return;
+};
 function flush(ctx, f, subscription) {
   f.chain = f.chain.then(async () => {
     if (f.failure)
@@ -254,18 +373,50 @@ function flush(ctx, f, subscription) {
   });
   return f.chain;
 }
-async function open(ctx, token) {
-  const f = {
+function following(token) {
+  return {
     pending: new Map,
     last: undefined,
     saved: token,
     inFlight: 0,
     timer: undefined,
     beat: undefined,
+    stopLease: noop,
+    heard: false,
     chain: Promise.resolve(),
     done: false,
     failure: undefined
   };
+}
+function stopFollowing(ctx, f) {
+  f.done = true;
+  clearTimeout(f.timer);
+  clearInterval(f.beat);
+  f.stopLease();
+  ctx.follower.running = false;
+}
+function settle(ctx, f, subscription, lease) {
+  const letGo = () => f.heard ? release(ctx, lease) : Promise.resolve();
+  return subscription.closed.then(async (reason) => {
+    stopFollowing(ctx, f);
+    try {
+      await f.chain.catch(noop);
+      if (f.failure)
+        throw f.failure;
+      if (reason === "invalidated")
+        await clearState(ctx);
+      return reason;
+    } finally {
+      await letGo();
+    }
+  }, async (error) => {
+    stopFollowing(ctx, f);
+    await letGo();
+    throw f.failure ?? failed(ctx.name, "following changes", error);
+  });
+}
+async function open(ctx, token, lease) {
+  const f = following(token);
   const handle = async (change) => {
     if (f.failure)
       throw f.failure;
@@ -294,41 +445,29 @@ async function open(ctx, token) {
   f.beat = setInterval(() => {
     flush(ctx, f, subscription).catch(() => subscription.close());
   }, ctx.positionIntervalMs);
-  const stop = () => {
-    f.done = true;
-    clearTimeout(f.timer);
-    clearInterval(f.beat);
-    ctx.follower.running = false;
-  };
-  const closed = subscription.closed.then(async (reason) => {
-    stop();
-    await f.chain.catch(() => {
-      return;
-    });
+  f.stopLease = keepLease(ctx, lease, () => {
     if (f.failure)
-      throw f.failure;
-    if (reason === "invalidated")
-      await clearState(ctx);
-    return reason;
-  }, (error) => {
-    stop();
-    throw f.failure ?? failed(ctx.name, "following changes", error);
+      return;
+    f.failure = leaseLost(ctx);
+    subscription.close();
   });
+  const closed = settle(ctx, f, subscription, lease);
   try {
     await subscription.ready;
   } catch (error) {
-    stop();
-    closed.catch(() => {
-      return;
-    });
+    stopFollowing(ctx, f);
+    closed.catch(noop);
     throw error;
   }
+  f.heard = true;
   ctx.follower.running = true;
   const close = async () => {
     try {
       await flush(ctx, f, subscription);
     } finally {
       await subscription.close();
+      if (f.inFlight === 0)
+        await closed.then(noop, noop);
     }
   };
   return {
@@ -339,25 +478,50 @@ async function open(ctx, token) {
     [Symbol.asyncDispose]: close
   };
 }
+
+// src/start.ts
+function historyLost(error) {
+  const code = error?.serverCode;
+  return code === 286 || code === 280;
+}
 async function start(ctx) {
   checkIdle(ctx, "start it twice");
+  const lease = await acquire(ctx, "start it");
+  const stop = keepLease(ctx, lease, () => {
+    return;
+  });
+  try {
+    const running = await startHeld(ctx, lease);
+    stop();
+    return running;
+  } catch (error) {
+    stop();
+    await release(ctx, lease);
+    throw error;
+  }
+}
+async function openHeld(ctx, token, lease) {
+  await confirmLease(ctx, lease);
+  return open(ctx, token, lease);
+}
+async function startHeld(ctx, lease) {
   let state = await readState(ctx);
   if (!state) {
-    await reindex(ctx);
+    await reindexHeld(ctx, lease);
     state = await readState(ctx);
   }
   try {
-    return await open(ctx, state.resumeToken);
+    return await openHeld(ctx, state.resumeToken, lease);
   } catch (error) {
     if (!historyLost(error))
       throw failed(ctx.name, "starting", error);
     if (ctx.onHistoryLost === "fail") {
       throw new SearchSyncError(`Search sync "${ctx.name}" was last at a point the server's change ` + "history no longer reaches. Reindex it, or start it with " + "onHistoryLost: 'reindex'.", { code: "HISTORY_LOST", sync: ctx.name, cause: error });
     }
-    await reindex(ctx);
+    await reindexHeld(ctx, lease);
     const fresh = await readState(ctx);
     try {
-      return await open(ctx, fresh.resumeToken);
+      return await openHeld(ctx, fresh.resumeToken, lease);
     } catch (again) {
       throw failed(ctx.name, "starting", again);
     }
@@ -379,5 +543,5 @@ export {
   createSearchSync
 };
 
-//# debugId=3F6CF388DE058E4464756E2164756E21
+//# debugId=663F5145BB58E86F64756E2164756E21
 //# sourceMappingURL=index.js.map