@everdeep/pubmed 0.1.1 → 0.1.2

package/README.md

@@ -77,12 +77,14 @@ Cursors are versioned, base64url-encoded, unsigned, implementation-specific cont
 
 ### Count changes during pagination
 
-NCBI can return HTTP 200 with valid IDs but a different total on a later page. By default, the client stops with `PaginationConsistencyError` (`code: "PAGINATION_INCONSISTENT"`, `retryable: false`), not `INVALID_RESPONSE` or `SEARCH_LIMIT`. This is a consistency signal, **not provider unavailability**. Retrying may succeed, but does not establish consistent results; the client does not automatically retry or restart such searches.
+NCBI can return HTTP 200 with valid IDs but a different total on a later page. By default, `search()` and `searchAll()` **continue retrieving valid pages**, returning count-drift diagnostics and emitting a `search-total-drift` event. The default `totalDriftPolicy` is `"warn"` (version 0.1.1 defaulted to `"error"`); no explicit opt-in or event handler is required. This is best-effort pagination, not a snapshot guarantee.
 
-If best-effort pagination is acceptable, opt in explicitly at client construction:
+To stop on count changes, explicitly configure `totalDriftPolicy: "error"`. Strict mode throws `PaginationConsistencyError` (`code: "PAGINATION_INCONSISTENT"`, `retryable: false`) before fetching the changed page's records. This is a consistency signal, **not provider unavailability**. The client does not automatically retry or restart such searches.
+
+With the default policy:
 
 ```ts
-const client = new PubMedClient({ email, tool, totalDriftPolicy: "warn" });
+const client = new PubMedClient({ email, tool }); // totalDriftPolicy: "warn" by default
 const first = await client.search({ query: "cancer", pageSize: 2 });
 if (first.nextCursor) {
   const second = await client.search({ cursor: first.nextCursor });
@@ -94,7 +96,7 @@ In both modes, `SearchBatch.total` and the pagination bound remain the **initial
 
 Warn mode returns a `diagnostics` entry on each drifted page and emits a `search-total-drift` event. A consistency error exposes the same metadata through `.diagnostic` and `toJSON()`: `reason`, `originalTotal`, `observedTotal`, `offset`, `requestedIds`, and `returnedIds`. No queries, PMIDs, cursors, or history tokens are included. Record parse `warnings` remain separate.
 
-Neither mode guarantees snapshot enumeration: equal counts do not prove stable membership or ordering, and page-local uniqueness does not detect cross-page duplicates or omissions. Warn mode explicitly accepts that risk; it does not silently deduplicate or claim complete results. Consumers requiring exact enumeration should not opt in.
+Neither mode guarantees snapshot enumeration: equal counts do not prove stable membership or ordering, and page-local uniqueness does not detect cross-page duplicates or omissions. Warn mode accepts that risk; it does not silently deduplicate or claim complete results. Consumers should persist by PMID idempotently and inspect `missingPmids` and `diagnostics`. Consumers requiring a stop on count drift should select `"error"`, but that alone does not establish exact enumeration.
 
 For progressive consumption, use `searchAll()`. `maxResults` is required so a caller must make the retrieval bound explicit:
 

package/dist/index.cjs

@@ -1567,7 +1567,9 @@ var Transport = class {
     const correlationId = (0, import_node_crypto.randomUUID)();
     safeEvent(this.#onEvent, { type: "correlation-id", endpoint, correlationId });
     try {
-      return await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      const value = await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      if (options.signal?.aborted) throw new AbortedError();
+      return value;
     } catch (error) {
       safeEvent(this.#onEvent, {
         type: "terminal-failure",
@@ -1591,6 +1593,7 @@ ${semantic.toString()}`);
       const cached = await this.#cache.read(key, signal);
       if (cached.status === "hit") {
         safeEvent(this.#onEvent, { type: "cache-hit", endpoint, correlationId });
+        if (signal?.aborted) throw new AbortedError();
         if (encoder.encode(cached.value).byteLength > this.#maxResponseBytes) {
           await this.#cache.invalidate(key);
         } else {
@@ -1902,7 +1905,7 @@ var PubMedClient = class {
     if (options.totalDriftPolicy !== void 0 && options.totalDriftPolicy !== "error" && options.totalDriftPolicy !== "warn") {
       throw new ValidationError('totalDriftPolicy must be "error" or "warn"');
     }
-    this.#totalDriftPolicy = options.totalDriftPolicy ?? "error";
+    this.#totalDriftPolicy = options.totalDriftPolicy ?? "warn";
     if (typeof options.email !== "string" || options.email.trim() === "") throw new ValidationError("email is required");
     if (typeof options.tool !== "string" || options.tool.trim() === "") throw new ValidationError("tool is required");
     if (options.apiKey !== void 0 && (typeof options.apiKey !== "string" || options.apiKey.trim() === "")) {
@@ -1966,6 +1969,7 @@ var PubMedClient = class {
     let ordered = input.flatMap((pmid) => byPmid.get(pmid) ?? []);
     if (unknown.length > 0) ordered = [...ordered, ...unknown];
     if (options.includeLinkOuts === true && ordered.length > 0) ordered = await this.#enrich(ordered, options.signal);
+    if (options.signal?.aborted) throw new AbortedError();
     return {
       records: ordered,
       missingPmids: input.filter((pmid) => !byPmid.has(pmid)),
@@ -1994,6 +1998,7 @@ var PubMedClient = class {
       );
       received.push(...summaries);
     }
+    if (options.signal?.aborted) throw new AbortedError();
     const byPmid = new Map(received.map((summary) => [summary.pmid, summary]));
     return {
       summaries: input.flatMap((pmid) => byPmid.get(pmid) ?? []),

package/dist/index.d.cts

@@ -408,7 +408,7 @@ interface PubMedClientOptions {
     readonly maxResponseBytes?: number;
     readonly maxQueuedRequests?: number;
     readonly maxBatchSize?: number;
-    /** Default "error". "warn" explicitly permits best-effort, non-snapshot pagination. */
+    /** Default "warn": continue valid pages with drift diagnostics. "error" opts into stopping on count changes. Neither guarantees a snapshot. */
     readonly totalDriftPolicy?: "error" | "warn";
 }
 

package/dist/index.d.ts

@@ -408,7 +408,7 @@ interface PubMedClientOptions {
     readonly maxResponseBytes?: number;
     readonly maxQueuedRequests?: number;
     readonly maxBatchSize?: number;
-    /** Default "error". "warn" explicitly permits best-effort, non-snapshot pagination. */
+    /** Default "warn": continue valid pages with drift diagnostics. "error" opts into stopping on count changes. Neither guarantees a snapshot. */
     readonly totalDriftPolicy?: "error" | "warn";
 }
 

package/dist/index.js

@@ -1522,7 +1522,9 @@ var Transport = class {
     const correlationId = randomUUID();
     safeEvent(this.#onEvent, { type: "correlation-id", endpoint, correlationId });
     try {
-      return await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      const value = await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      if (options.signal?.aborted) throw new AbortedError();
+      return value;
     } catch (error) {
       safeEvent(this.#onEvent, {
         type: "terminal-failure",
@@ -1546,6 +1548,7 @@ ${semantic.toString()}`);
       const cached = await this.#cache.read(key, signal);
       if (cached.status === "hit") {
         safeEvent(this.#onEvent, { type: "cache-hit", endpoint, correlationId });
+        if (signal?.aborted) throw new AbortedError();
         if (encoder.encode(cached.value).byteLength > this.#maxResponseBytes) {
           await this.#cache.invalidate(key);
         } else {
@@ -1857,7 +1860,7 @@ var PubMedClient = class {
     if (options.totalDriftPolicy !== void 0 && options.totalDriftPolicy !== "error" && options.totalDriftPolicy !== "warn") {
       throw new ValidationError('totalDriftPolicy must be "error" or "warn"');
     }
-    this.#totalDriftPolicy = options.totalDriftPolicy ?? "error";
+    this.#totalDriftPolicy = options.totalDriftPolicy ?? "warn";
     if (typeof options.email !== "string" || options.email.trim() === "") throw new ValidationError("email is required");
     if (typeof options.tool !== "string" || options.tool.trim() === "") throw new ValidationError("tool is required");
     if (options.apiKey !== void 0 && (typeof options.apiKey !== "string" || options.apiKey.trim() === "")) {
@@ -1921,6 +1924,7 @@ var PubMedClient = class {
     let ordered = input.flatMap((pmid) => byPmid.get(pmid) ?? []);
     if (unknown.length > 0) ordered = [...ordered, ...unknown];
     if (options.includeLinkOuts === true && ordered.length > 0) ordered = await this.#enrich(ordered, options.signal);
+    if (options.signal?.aborted) throw new AbortedError();
     return {
       records: ordered,
       missingPmids: input.filter((pmid) => !byPmid.has(pmid)),
@@ -1949,6 +1953,7 @@ var PubMedClient = class {
       );
       received.push(...summaries);
     }
+    if (options.signal?.aborted) throw new AbortedError();
     const byPmid = new Map(received.map((summary) => [summary.pmid, summary]));
     return {
       summaries: input.flatMap((pmid) => byPmid.get(pmid) ?? []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everdeep/pubmed",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Safe, typed TypeScript client for the NCBI PubMed E-utilities API",
   "type": "module",
   "main": "./dist/index.cjs",