@gitkraken/core-gitlens 0.6.0 → 0.7.0

package/dist/plus/integrations/reads/paging.js

@@ -1,281 +1,264 @@
-import { PagingMode } from '../providers/models.js';
-import { mergeCollectionMetadata, parsePageCursor, toPageCursor } from '../providers/utils/providerPaging.js';
-import { appendDedupedWarning } from '../results.js';
+import { appendDedupedWarning } from "../results.js";
+import "../providers/models.js";
+import { mergeCollectionMetadata, parsePageCursor, toPageCursor } from "../providers/utils/providerPaging.js";
+//#region ../plus/integrations/src/reads/paging.ts
 /**
- * The paging mechanics shared by every paged read on the provider facade: translating the SDK's `paging` into
- * the page-oriented shape consumers get, deciding what position and what continuation a page may honestly
- * claim, and walking a cursor-only read forward to a requested page number.
- *
- * Kept in one module because the value of these rules is that they are the SAME on every read — the contract
- * they implement is documented once on {@link ProviderPageInfo} and on `IntegrationManager`'s paging section.
- * Copies of them drifting apart is exactly the defect this consolidation removed.
- */
+* The paging mechanics shared by every paged read on the provider facade: translating the SDK's `paging` into
+* the page-oriented shape consumers get, deciding what position and what continuation a page may honestly
+* claim, and walking a cursor-only read forward to a requested page number.
+*
+* Kept in one module because the value of these rules is that they are the SAME on every read — the contract
+* they implement is documented once on {@link ProviderPageInfo} and on `IntegrationManager`'s paging section.
+* Copies of them drifting apart is exactly the defect this consolidation removed.
+*/
 /**
- * Whether a repo-scoped read for this provider ADVANCES on a page number, so the facade may synthesize a
- * page-number cursor, `page.currentPage` may echo the request, and a next-page number is a usable continuation.
- *
- * Only `PagingMode.Repos` (GitHub/GHE) is excluded: its read is cursor-only, so it accepts a page number and
- * ignores it, answering with page 1 — which is why {@link drainToRequestedPage} exists for that mode.
- *
- * Every other provider, including one with no declared mode (Bitbucket Data Center), reads `page` as a 1-based
- * page number. That last part is only true as of `@gitkraken/provider-apis` 0.54.0: before it, Bitbucket Data
- * Center consumed `page` as a raw `start` ITEM OFFSET, so a synthesized page 3 asked for `start=3` — a window
- * overlapping page 1 — and this facade had to withhold the synthesized cursor from it. The SDK now converts
- * (`start = (page - 1) * limit`) and reports `nextPage` as a page number, so the guard is gone and that host
- * can be advanced by number like the rest.
- */
-export function isPageNumberAdvanceable(mode) {
-    return mode !== PagingMode.Repos;
+* Whether a repo-scoped read for this provider ADVANCES on a page number, so the facade may synthesize a
+* page-number cursor, `page.currentPage` may echo the request, and a next-page number is a usable continuation.
+*
+* Only `PagingMode.Repos` (GitHub/GHE) is excluded: its read is cursor-only, so it accepts a page number and
+* ignores it, answering with page 1 — which is why {@link drainToRequestedPage} exists for that mode.
+*
+* Every other provider, including one with no declared mode (Bitbucket Data Center), reads `page` as a 1-based
+* page number. That last part is only true as of `@gitkraken/provider-apis` 0.54.0: before it, Bitbucket Data
+* Center consumed `page` as a raw `start` ITEM OFFSET, so a synthesized page 3 asked for `start=3` — a window
+* overlapping page 1 — and this facade had to withhold the synthesized cursor from it. The SDK now converts
+* (`start = (page - 1) * limit`) and reports `nextPage` as a page number, so the guard is gone and that host
+* can be advanced by number like the rest.
+*/
+function isPageNumberAdvanceable(mode) {
+	return mode !== "repos";
 }
 /**
- * Encodes a 1-based page number as the opaque cursor the provider paging layer understands, via the same
- * {@link toPageCursor} the providers encode with (its `parsePageCursor` counterpart is what reads these back).
- * Page 1 needs no cursor: it is the read's own starting position.
- */
-export function pageToCursor(page) {
-    return page == null || page <= 1 ? undefined : toPageCursor(page);
+* Encodes a 1-based page number as the opaque cursor the provider paging layer understands, via the same
+* {@link toPageCursor} the providers encode with (its `parsePageCursor` counterpart is what reads these back).
+* Page 1 needs no cursor: it is the read's own starting position.
+*/
+function pageToCursor(page) {
+	return page == null || page <= 1 ? void 0 : toPageCursor(page);
 }
 /**
- * Filters out the provider paging layer's empty-cursor sentinel. `providersApi` seeds its next-cursor with
- * `'{}'` and leaves it there when the SDK reports another page without an `endCursor`, so `'{}'` means "no
- * usable continuation" and must never be threaded back as one.
- */
-export function usableCursor(cursor) {
-    return cursor == null || cursor === '{}' ? undefined : cursor;
+* Filters out the provider paging layer's empty-cursor sentinel. `providersApi` seeds its next-cursor with
+* `'{}'` and leaves it there when the SDK reports another page without an `endCursor`, so `'{}'` means "no
+* usable continuation" and must never be threaded back as one.
+*/
+function usableCursor(cursor) {
+	return cursor == null || cursor === "{}" ? void 0 : cursor;
 }
 /**
- * The terminal page a paged read returns when it refuses the request outright — the surface doesn't apply (an
- * issue tracker asked for a repo read), the target couldn't be resolved, a capability is missing, or a filter
- * set isn't expressible server-side. Every one of those is "no page was served": empty `items`, no continuation,
- * and the reason carried in `warnings`.
- *
- * `currentPage` stays a caller-supplied parameter rather than being derived here because the refusals differ on
- * what position they can honestly claim: a read the provider advances by page number reports the requested page,
- * while a cursor-only account-wide read has no addressable position and reports 1 (see
- * {@link ProviderPageInfo.currentPage}).
- */
-export function refusedPage(currentPage, warnings, fetchFailed) {
-    return {
-        items: [],
-        warnings: warnings,
-        page: { currentPage: currentPage, itemsPerPage: 0 },
-        hasMore: false,
-        fetchFailed: fetchFailed || undefined,
-    };
+* The terminal page a paged read returns when it refuses the request outright — the surface doesn't apply (an
+* issue tracker asked for a repo read), the target couldn't be resolved, a capability is missing, or a filter
+* set isn't expressible server-side. Every one of those is "no page was served": empty `items`, no continuation,
+* and the reason carried in `warnings`.
+*
+* `currentPage` stays a caller-supplied parameter rather than being derived here because the refusals differ on
+* what position they can honestly claim: a read the provider advances by page number reports the requested page,
+* while a cursor-only account-wide read has no addressable position and reports 1 (see
+* {@link ProviderPageInfo.currentPage}).
+*/
+function refusedPage(currentPage, warnings, fetchFailed) {
+	return {
+		items: [],
+		warnings,
+		page: {
+			currentPage,
+			itemsPerPage: 0
+		},
+		hasMore: false,
+		fetchFailed: fetchFailed || void 0
+	};
 }
 /**
- * Normalizes a `PagedResult.paging` into the page-oriented shape Kepler consumes: `page`, `hasMore`, and an
- * opaque `cursor` retained only for cursor-only hosts (where jumping straight to page N isn't possible, so the
- * caller threads the cursor back instead).
- */
-export function toProviderPageInfo(itemsPerPage, paging) {
-    let cursor;
-    let cursorPage;
-    const raw = paging?.cursor;
-    if (raw != null && raw !== '{}') {
-        try {
-            const parsed = JSON.parse(raw);
-            // Retain opaque cursor strings for cursor-only hosts, per-repo/project cursor bundles for
-            // PagingMode.Repo/Project reads, AND page/offset cursors. The latter matters for reads with no
-            // caller-visible page param to increment — e.g. Bitbucket Server's account-wide PR read threads
-            // its next `start` offset as a `type:'page'` cursor; dropping it left the caller with
-            // `hasMore:true` and nothing to continue with. A page cursor is a valid opaque continuation, so
-            // threading it back is always safe even where a page number is also reported.
-            if (parsed.type === 'cursor' || parsed.type === 'page' || Array.isArray(parsed.cursors)) {
-                cursor = raw;
-                // Per-repo/project cursor bundles also carry the current page number so the facade can report the
-                // real page when the consumer continues using only the cursor.
-                if (Array.isArray(parsed.cursors) && parsed.page != null) {
-                    cursorPage = parsed.page;
-                }
-            }
-        }
-        catch { }
-    }
-    // Only echo a page number the provider actually honored. Numbered-page hosts report their own
-    // `paging.page`; cursor-only hosts (e.g. GitHub PR search) report none and ignore a synthesized
-    // page-number cursor — returning their first page — so echoing the requested `page` would mislabel
-    // page 1 as page N. Report page 1 in that case rather than the unapplied request. Per-repo/project
-    // bundles may carry the page explicitly in the cursor.
-    const currentPage = paging?.page ?? cursorPage ?? 1;
-    return {
-        page: {
-            currentPage: Math.max(1, currentPage),
-            itemsPerPage: paging?.pageSize ?? itemsPerPage,
-        },
-        hasMore: paging?.more ?? false,
-        cursor: cursor,
-        // A single-page provider read that couldn't confirm completeness carries `paging.truncated`;
-        // surface it so callers can flag `page.truncated` instead of publishing a partial read as complete.
-        truncated: paging?.truncated ?? false,
-    };
+* Normalizes a `PagedResult.paging` into the page-oriented shape Kepler consumes: `page`, `hasMore`, and an
+* opaque `cursor` retained only for cursor-only hosts (where jumping straight to page N isn't possible, so the
+* caller threads the cursor back instead).
+*/
+function toProviderPageInfo(itemsPerPage, paging) {
+	let cursor;
+	let cursorPage;
+	const raw = paging?.cursor;
+	if (raw != null && raw !== "{}") try {
+		const parsed = JSON.parse(raw);
+		if (parsed.type === "cursor" || parsed.type === "page" || Array.isArray(parsed.cursors)) {
+			cursor = raw;
+			if (Array.isArray(parsed.cursors) && parsed.page != null) cursorPage = parsed.page;
+		}
+	} catch {}
+	const currentPage = paging?.page ?? cursorPage ?? 1;
+	return {
+		page: {
+			currentPage: Math.max(1, currentPage),
+			itemsPerPage: paging?.pageSize ?? itemsPerPage
+		},
+		hasMore: paging?.more ?? false,
+		cursor,
+		truncated: paging?.truncated ?? false
+	};
 }
 /**
- * Reconciles a provider's `hasMore` with the continuation it actually handed back. A provider can report
- * `hasNextPage: true` while omitting the `endCursor` (the paging layer surfaces that as the sentinel `'{}'`,
- * which {@link toProviderPageInfo} drops), leaving `hasMore: true` with no cursor — a consumer that pages while
- * `hasMore` would then re-request the same page forever. Prefer the real provider cursor; else synthesize the
- * next page number, but only for a read the provider actually advances by page number (`nextPage` omitted for
- * cursor-only reads, which ignore it and answer with their first page again); else report the read as
- * terminal-but-incomplete (`hasMore: false` + `truncated`).
- */
-export function resolveContinuation(paged, nextPage) {
-    if (!paged.hasMore)
-        return { hasMore: false, cursor: undefined, truncated: paged.truncated };
-    if (paged.cursor != null)
-        return { hasMore: true, cursor: paged.cursor, truncated: paged.truncated };
-    const synthesized = nextPage != null ? pageToCursor(nextPage) : undefined;
-    if (synthesized != null)
-        return { hasMore: true, cursor: synthesized, truncated: paged.truncated };
-    return { hasMore: false, cursor: undefined, truncated: true };
+* Reconciles a provider's `hasMore` with the continuation it actually handed back. A provider can report
+* `hasNextPage: true` while omitting the `endCursor` (the paging layer surfaces that as the sentinel `'{}'`,
+* which {@link toProviderPageInfo} drops), leaving `hasMore: true` with no cursor — a consumer that pages while
+* `hasMore` would then re-request the same page forever. Prefer the real provider cursor; else synthesize the
+* next page number, but only for a read the provider actually advances by page number (`nextPage` omitted for
+* cursor-only reads, which ignore it and answer with their first page again); else report the read as
+* terminal-but-incomplete (`hasMore: false` + `truncated`).
+*/
+function resolveContinuation(paged, nextPage) {
+	if (!paged.hasMore) return {
+		hasMore: false,
+		cursor: void 0,
+		truncated: paged.truncated
+	};
+	if (paged.cursor != null) return {
+		hasMore: true,
+		cursor: paged.cursor,
+		truncated: paged.truncated
+	};
+	const synthesized = nextPage != null ? pageToCursor(nextPage) : void 0;
+	if (synthesized != null) return {
+		hasMore: true,
+		cursor: synthesized,
+		truncated: paged.truncated
+	};
+	return {
+		hasMore: false,
+		cursor: void 0,
+		truncated: true
+	};
 }
 /**
- * Resolves the position a paged read reports as `page.currentPage`, per the single convention documented on
- * {@link ProviderPageInfo.currentPage}. Every paged read routes through here so the field means the same thing
- * on all of them: positional, never constant-1 for one read and positional for another.
- *
- * `providerPage` is what the provider (or the internal drain) established — 1 means "nothing reported".
- * `pageAdvanceable` is whether the read honors a page number at all: false for a cursor-only read, which
- * answers with its first page when handed a synthesized page-number cursor, so the requested `page` must NOT be
- * echoed there.
- */
-export function resolveCurrentPage(options) {
-    if (options.providerPage > 1)
-        return options.providerPage;
-    // A caller-threaded cursor DID advance the provider, so the caller's own position is authoritative for a
-    // provider that reports none: prefer the page the cursor encodes, else the `page` supplied alongside it.
-    if (options.suppliedCursor != null)
-        return parsePageCursor(options.suppliedCursor) ?? options.requestedPage;
-    return options.pageAdvanceable ? options.requestedPage : 1;
+* Resolves the position a paged read reports as `page.currentPage`, per the single convention documented on
+* {@link ProviderPageInfo.currentPage}. Every paged read routes through here so the field means the same thing
+* on all of them: positional, never constant-1 for one read and positional for another.
+*
+* `providerPage` is what the provider (or the internal drain) established — 1 means "nothing reported".
+* `pageAdvanceable` is whether the read honors a page number at all: false for a cursor-only read, which
+* answers with its first page when handed a synthesized page-number cursor, so the requested `page` must NOT be
+* echoed there.
+*/
+function resolveCurrentPage(options) {
+	if (options.providerPage > 1) return options.providerPage;
+	if (options.suppliedCursor != null) return parsePageCursor(options.suppliedCursor) ?? options.requestedPage;
+	return options.pageAdvanceable ? options.requestedPage : 1;
 }
 /**
- * Walks a FLAT cursor-paged read forward to a requested page number, for a provider whose pages are
- * `{cursor, hasMore, page, truncated}` rather than the SDK's `PagedResult` wrapper.
- *
- * The sibling of {@link drainToRequestedPage}, not a replacement for it: that one normalizes SDK `paging` through
- * {@link toProviderPageInfo}, which retains only cursors whose JSON declares `type`/`cursors` — and the composite
- * cursor of a GitHub aliased search declares neither, so it would be dropped and the walk would never advance.
- * Two shapes genuinely need two entry points; what they must NOT have is two copies of the rules below, which is
- * what this exists to prevent (see this module's own note on drift).
- *
- * The rules, all of them subtle enough to be worth stating once:
- * - The empty-cursor sentinel is filtered, so a provider claiming another page without handing back a usable
- *   continuation is not re-read with `'{}'` (which it would answer with page 1 again).
- * - A provider that returns the SAME cursor isn't advancing: stop, and report the read as truncated rather than
- *   looping forever or publishing a short page as complete.
- * - A page requested past the provider's terminal cursor is that EMPTY page N — never the last available page
- *   relabeled, per {@link ProviderPageInfo.currentPage}.
- * - A page that fails mid-walk latches `fetchFailed` and leaves no value, so the caller can tell "the read broke"
- *   from "the page was genuinely empty".
- *
- * `fold` is the one thing the callers differ on — one merges SDK collection metadata across the walked pages, the
- * other keeps the largest reported match count — so it is a callback rather than a branch.
- */
-export async function drainFlatPagesToRequestedPage(first, options) {
-    let value = first.value;
-    let fetchFailed = first.warning != null && value == null;
-    let currentPage = value?.page ?? 1;
-    let truncated = value?.truncated ?? false;
-    const walkable = options.suppliedCursor == null && options.requestedPage > 1;
-    if (walkable && value != null) {
-        for (let nextCursor = usableCursor(value.cursor); currentPage < options.requestedPage && value.hasMore === true && nextCursor != null; nextCursor = usableCursor(value.cursor)) {
-            const next = await options.readPage(nextCursor);
-            if (next.warning != null) {
-                appendDedupedWarning(options.warnings, next.warning);
-            }
-            if (next.value == null) {
-                fetchFailed = next.warning != null;
-                value = undefined;
-                break;
-            }
-            value = next.value;
-            truncated = truncated || value.truncated;
-            options.fold?.(value);
-            currentPage = value.page ?? currentPage + 1;
-            if (usableCursor(value.cursor) === nextCursor) {
-                truncated = true;
-                break;
-            }
-        }
-    }
-    return {
-        value: value,
-        currentPage: currentPage,
-        truncated: truncated,
-        // Every case reduces to "a page was asked for by number and the walk fell short", including the one where
-        // no walk ran at all because the first page was already terminal.
-        requestedPageMissing: walkable && currentPage < options.requestedPage,
-        fetchFailed: fetchFailed,
-    };
+* Walks a FLAT cursor-paged read forward to a requested page number, for a provider whose pages are
+* `{cursor, hasMore, page, truncated}` rather than the SDK's `PagedResult` wrapper.
+*
+* The sibling of {@link drainToRequestedPage}, not a replacement for it: that one normalizes SDK `paging` through
+* {@link toProviderPageInfo}, which retains only cursors whose JSON declares `type`/`cursors` — and the composite
+* cursor of a GitHub aliased search declares neither, so it would be dropped and the walk would never advance.
+* Two shapes genuinely need two entry points; what they must NOT have is two copies of the rules below, which is
+* what this exists to prevent (see this module's own note on drift).
+*
+* The rules, all of them subtle enough to be worth stating once:
+* - The empty-cursor sentinel is filtered, so a provider claiming another page without handing back a usable
+*   continuation is not re-read with `'{}'` (which it would answer with page 1 again).
+* - A provider that returns the SAME cursor isn't advancing: stop, and report the read as truncated rather than
+*   looping forever or publishing a short page as complete.
+* - A page requested past the provider's terminal cursor is that EMPTY page N — never the last available page
+*   relabeled, per {@link ProviderPageInfo.currentPage}.
+* - A page that fails mid-walk latches `fetchFailed` and leaves no value, so the caller can tell "the read broke"
+*   from "the page was genuinely empty".
+*
+* `fold` is the one thing the callers differ on — one merges SDK collection metadata across the walked pages, the
+* other keeps the largest reported match count — so it is a callback rather than a branch.
+*/
+async function drainFlatPagesToRequestedPage(first, options) {
+	let value = first.value;
+	let fetchFailed = first.warning != null && value == null;
+	let currentPage = value?.page ?? 1;
+	let truncated = value?.truncated ?? false;
+	const walkable = options.suppliedCursor == null && options.requestedPage > 1;
+	if (walkable && value != null) for (let nextCursor = usableCursor(value.cursor); currentPage < options.requestedPage && value.hasMore === true && nextCursor != null; nextCursor = usableCursor(value.cursor)) {
+		const next = await options.readPage(nextCursor);
+		if (next.warning != null) appendDedupedWarning(options.warnings, next.warning);
+		if (next.value == null) {
+			fetchFailed = next.warning != null;
+			value = void 0;
+			break;
+		}
+		value = next.value;
+		truncated = truncated || value.truncated;
+		options.fold?.(value);
+		currentPage = value.page ?? currentPage + 1;
+		if (usableCursor(value.cursor) === nextCursor) {
+			truncated = true;
+			break;
+		}
+	}
+	return {
+		value,
+		currentPage,
+		truncated,
+		requestedPageMissing: walkable && currentPage < options.requestedPage,
+		fetchFailed
+	};
 }
 /**
- * Advances a cursor-only read to the requested page when the caller supplied only `page`.
- *
- * A cursor-only read accepts a synthesized page-number cursor and ignores it, answering with its first page, so
- * the requested page has to be reached by walking the provider's own opaque continuations. Only the last
- * successfully-read page's items are kept — returning pages 1..N as "page N" would duplicate items for a normal
- * paged consumer — while warnings and metadata are merged across the whole drained prefix.
- *
- * Shared by the repo-scoped and account-wide PR reads and the repo-scoped issue read so the three cannot drift:
- * a requested page past the provider's terminal cursor is an EMPTY page N on all of them, per
- * {@link ProviderPageInfo.currentPage}, never the last available page relabeled.
- */
-export async function drainToRequestedPage(state, options) {
-    let { items, metadata, fetchFailed } = state;
-    let currentPage = 1;
-    let currentCursor = usableCursor(state.paged.hasMore ? state.paged.cursor : undefined);
-    let currentHasMore = state.paged.hasMore && currentCursor != null;
-    let currentTruncated = state.paged.truncated;
-    // A page requested past the terminal cursor is that empty page N. Distinguished from the first read
-    // having failed outright, which is already reported as page N with no items by the caller's own state.
-    const missRequestedPage = () => {
-        items = [];
-        currentPage = options.requestedPage;
-        currentCursor = undefined;
-        currentHasMore = false;
-    };
-    if (fetchFailed) {
-        missRequestedPage();
-    }
-    while (currentPage < options.requestedPage && currentHasMore && currentCursor != null) {
-        const { value, warning } = await options.readPage(currentCursor);
-        if (warning != null) {
-            appendDedupedWarning(options.warnings, warning);
-        }
-        if (value == null) {
-            fetchFailed = true;
-            missRequestedPage();
-            break;
-        }
-        items = value.values;
-        metadata = mergeCollectionMetadata(metadata, value.metadata);
-        const next = toProviderPageInfo(options.itemsPerPage ?? value.values.length, value.paging);
-        currentPage++;
-        currentTruncated ||= next.truncated;
-        const nextCursor = usableCursor(next.cursor);
-        // A provider that hands back the same cursor (or none) isn't advancing; stop rather than refetch
-        // the same page forever.
-        if (nextCursor == null || nextCursor === currentCursor) {
-            currentCursor = undefined;
-            currentHasMore = false;
-            break;
-        }
-        currentCursor = nextCursor;
-        currentHasMore = next.hasMore;
-    }
-    if (currentPage < options.requestedPage) {
-        missRequestedPage();
-    }
-    return {
-        items: items,
-        paged: {
-            page: { currentPage: currentPage, itemsPerPage: options.itemsPerPage ?? items.length },
-            hasMore: currentHasMore,
-            cursor: currentCursor,
-            truncated: currentTruncated,
-        },
-        metadata: metadata,
-        fetchFailed: fetchFailed,
-    };
+* Advances a cursor-only read to the requested page when the caller supplied only `page`.
+*
+* A cursor-only read accepts a synthesized page-number cursor and ignores it, answering with its first page, so
+* the requested page has to be reached by walking the provider's own opaque continuations. Only the last
+* successfully-read page's items are kept — returning pages 1..N as "page N" would duplicate items for a normal
+* paged consumer — while warnings and metadata are merged across the whole drained prefix.
+*
+* Shared by the repo-scoped and account-wide PR reads and the repo-scoped issue read so the three cannot drift:
+* a requested page past the provider's terminal cursor is an EMPTY page N on all of them, per
+* {@link ProviderPageInfo.currentPage}, never the last available page relabeled.
+*/
+async function drainToRequestedPage(state, options) {
+	let { items, metadata, fetchFailed } = state;
+	let currentPage = 1;
+	let currentCursor = usableCursor(state.paged.hasMore ? state.paged.cursor : void 0);
+	let currentHasMore = state.paged.hasMore && currentCursor != null;
+	let currentTruncated = state.paged.truncated;
+	const missRequestedPage = () => {
+		items = [];
+		currentPage = options.requestedPage;
+		currentCursor = void 0;
+		currentHasMore = false;
+	};
+	if (fetchFailed) missRequestedPage();
+	while (currentPage < options.requestedPage && currentHasMore && currentCursor != null) {
+		const { value, warning } = await options.readPage(currentCursor);
+		if (warning != null) appendDedupedWarning(options.warnings, warning);
+		if (value == null) {
+			fetchFailed = true;
+			missRequestedPage();
+			break;
+		}
+		items = value.values;
+		metadata = mergeCollectionMetadata(metadata, value.metadata);
+		const next = toProviderPageInfo(options.itemsPerPage ?? value.values.length, value.paging);
+		currentPage++;
+		currentTruncated ||= next.truncated;
+		const nextCursor = usableCursor(next.cursor);
+		if (nextCursor == null || nextCursor === currentCursor) {
+			currentCursor = void 0;
+			currentHasMore = false;
+			break;
+		}
+		currentCursor = nextCursor;
+		currentHasMore = next.hasMore;
+	}
+	if (currentPage < options.requestedPage) missRequestedPage();
+	return {
+		items,
+		paged: {
+			page: {
+				currentPage,
+				itemsPerPage: options.itemsPerPage ?? items.length
+			},
+			hasMore: currentHasMore,
+			cursor: currentCursor,
+			truncated: currentTruncated
+		},
+		metadata,
+		fetchFailed
+	};
 }
+//#endregion
+export { drainFlatPagesToRequestedPage, drainToRequestedPage, isPageNumberAdvanceable, pageToCursor, refusedPage, resolveContinuation, resolveCurrentPage, toProviderPageInfo, usableCursor };
+
 //# sourceMappingURL=paging.js.map

package/dist/plus/integrations/reads/paging.js.map

@@ -1 +1 @@
-{"version":3,"file":"paging.js","sourceRoot":"","sources":["../../../../src/plus/integrations/reads/paging.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paging.js","names":[],"sources":["../../../../../plus/integrations/src/reads/paging.ts"],"sourcesContent":["import type { CollectionMetadata } from '@gitkraken/provider-apis';\nimport type { PagedResult } from '@gitlens/utils/paging.js';\nimport { PagingMode } from '../providers/models.js';\nimport { mergeCollectionMetadata, parsePageCursor, toPageCursor } from '../providers/utils/providerPaging.js';\nimport type { ProviderPagedResult, ProviderPageInfo, ProviderWarning } from '../results.js';\nimport { appendDedupedWarning } from '../results.js';\n\n/**\n * The paging mechanics shared by every paged read on the provider facade: translating the SDK's `paging` into\n * the page-oriented shape consumers get, deciding what position and what continuation a page may honestly\n * claim, and walking a cursor-only read forward to a requested page number.\n *\n * Kept in one module because the value of these rules is that they are the SAME on every read — the contract\n * they implement is documented once on {@link ProviderPageInfo} and on `IntegrationManager`'s paging section.\n * Copies of them drifting apart is exactly the defect this consolidation removed.\n */\n\n/**\n * Whether a repo-scoped read for this provider ADVANCES on a page number, so the facade may synthesize a\n * page-number cursor, `page.currentPage` may echo the request, and a next-page number is a usable continuation.\n *\n * Only `PagingMode.Repos` (GitHub/GHE) is excluded: its read is cursor-only, so it accepts a page number and\n * ignores it, answering with page 1 — which is why {@link drainToRequestedPage} exists for that mode.\n *\n * Every other provider, including one with no declared mode (Bitbucket Data Center), reads `page` as a 1-based\n * page number. That last part is only true as of `@gitkraken/provider-apis` 0.54.0: before it, Bitbucket Data\n * Center consumed `page` as a raw `start` ITEM OFFSET, so a synthesized page 3 asked for `start=3` — a window\n * overlapping page 1 — and this facade had to withhold the synthesized cursor from it. The SDK now converts\n * (`start = (page - 1) * limit`) and reports `nextPage` as a page number, so the guard is gone and that host\n * can be advanced by number like the rest.\n */\nexport function isPageNumberAdvanceable(mode: PagingMode | undefined): boolean {\n\treturn mode !== PagingMode.Repos;\n}\n\n/**\n * Encodes a 1-based page number as the opaque cursor the provider paging layer understands, via the same\n * {@link toPageCursor} the providers encode with (its `parsePageCursor` counterpart is what reads these back).\n * Page 1 needs no cursor: it is the read's own starting position.\n */\nexport function pageToCursor(page: number | undefined): string | undefined {\n\treturn page == null || page <= 1 ? undefined : toPageCursor(page);\n}\n\n/**\n * Filters out the provider paging layer's empty-cursor sentinel. `providersApi` seeds its next-cursor with\n * `'{}'` and leaves it there when the SDK reports another page without an `endCursor`, so `'{}'` means \"no\n * usable continuation\" and must never be threaded back as one.\n */\nexport function usableCursor(cursor: string | undefined): string | undefined {\n\treturn cursor == null || cursor === '{}' ? undefined : cursor;\n}\n\n/**\n * The terminal page a paged read returns when it refuses the request outright — the surface doesn't apply (an\n * issue tracker asked for a repo read), the target couldn't be resolved, a capability is missing, or a filter\n * set isn't expressible server-side. Every one of those is \"no page was served\": empty `items`, no continuation,\n * and the reason carried in `warnings`.\n *\n * `currentPage` stays a caller-supplied parameter rather than being derived here because the refusals differ on\n * what position they can honestly claim: a read the provider advances by page number reports the requested page,\n * while a cursor-only account-wide read has no addressable position and reports 1 (see\n * {@link ProviderPageInfo.currentPage}).\n */\nexport function refusedPage<T>(\n\tcurrentPage: number,\n\twarnings: ProviderWarning[],\n\tfetchFailed: boolean,\n): ProviderPagedResult<T> {\n\treturn {\n\t\titems: [],\n\t\twarnings: warnings,\n\t\tpage: { currentPage: currentPage, itemsPerPage: 0 },\n\t\thasMore: false,\n\t\tfetchFailed: fetchFailed || undefined,\n\t};\n}\n\n/** A provider page normalized off the SDK's `paging`, before continuation and position are reconciled. */\nexport interface NormalizedPage {\n\tpage: ProviderPageInfo;\n\thasMore: boolean;\n\tcursor?: string;\n\ttruncated: boolean;\n}\n\n/**\n * Normalizes a `PagedResult.paging` into the page-oriented shape Kepler consumes: `page`, `hasMore`, and an\n * opaque `cursor` retained only for cursor-only hosts (where jumping straight to page N isn't possible, so the\n * caller threads the cursor back instead).\n */\nexport function toProviderPageInfo(\n\titemsPerPage: number,\n\tpaging: { more?: boolean; cursor?: string; page?: number; pageSize?: number; truncated?: boolean } | undefined,\n): NormalizedPage {\n\tlet cursor: string | undefined;\n\tlet cursorPage: number | undefined;\n\tconst raw = paging?.cursor;\n\tif (raw != null && raw !== '{}') {\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(raw) as { type?: string; cursors?: unknown; page?: number };\n\t\t\t// Retain opaque cursor strings for cursor-only hosts, per-repo/project cursor bundles for\n\t\t\t// PagingMode.Repo/Project reads, AND page/offset cursors. The latter matters for reads with no\n\t\t\t// caller-visible page param to increment — e.g. Bitbucket Server's account-wide PR read threads\n\t\t\t// its next `start` offset as a `type:'page'` cursor; dropping it left the caller with\n\t\t\t// `hasMore:true` and nothing to continue with. A page cursor is a valid opaque continuation, so\n\t\t\t// threading it back is always safe even where a page number is also reported.\n\t\t\tif (parsed.type === 'cursor' || parsed.type === 'page' || Array.isArray(parsed.cursors)) {\n\t\t\t\tcursor = raw;\n\t\t\t\t// Per-repo/project cursor bundles also carry the current page number so the facade can report the\n\t\t\t\t// real page when the consumer continues using only the cursor.\n\t\t\t\tif (Array.isArray(parsed.cursors) && parsed.page != null) {\n\t\t\t\t\tcursorPage = parsed.page;\n\t\t\t\t}\n\t\t\t}\n\t\t} catch {}\n\t}\n\t// Only echo a page number the provider actually honored. Numbered-page hosts report their own\n\t// `paging.page`; cursor-only hosts (e.g. GitHub PR search) report none and ignore a synthesized\n\t// page-number cursor — returning their first page — so echoing the requested `page` would mislabel\n\t// page 1 as page N. Report page 1 in that case rather than the unapplied request. Per-repo/project\n\t// bundles may carry the page explicitly in the cursor.\n\tconst currentPage = paging?.page ?? cursorPage ?? 1;\n\treturn {\n\t\tpage: {\n\t\t\tcurrentPage: Math.max(1, currentPage),\n\t\t\titemsPerPage: paging?.pageSize ?? itemsPerPage,\n\t\t},\n\t\thasMore: paging?.more ?? false,\n\t\tcursor: cursor,\n\t\t// A single-page provider read that couldn't confirm completeness carries `paging.truncated`;\n\t\t// surface it so callers can flag `page.truncated` instead of publishing a partial read as complete.\n\t\ttruncated: paging?.truncated ?? false,\n\t};\n}\n\n/**\n * Reconciles a provider's `hasMore` with the continuation it actually handed back. A provider can report\n * `hasNextPage: true` while omitting the `endCursor` (the paging layer surfaces that as the sentinel `'{}'`,\n * which {@link toProviderPageInfo} drops), leaving `hasMore: true` with no cursor — a consumer that pages while\n * `hasMore` would then re-request the same page forever. Prefer the real provider cursor; else synthesize the\n * next page number, but only for a read the provider actually advances by page number (`nextPage` omitted for\n * cursor-only reads, which ignore it and answer with their first page again); else report the read as\n * terminal-but-incomplete (`hasMore: false` + `truncated`).\n */\nexport function resolveContinuation(\n\tpaged: { hasMore: boolean; cursor?: string; truncated: boolean },\n\tnextPage: number | undefined,\n): { hasMore: boolean; cursor?: string; truncated: boolean } {\n\tif (!paged.hasMore) return { hasMore: false, cursor: undefined, truncated: paged.truncated };\n\tif (paged.cursor != null) return { hasMore: true, cursor: paged.cursor, truncated: paged.truncated };\n\n\tconst synthesized = nextPage != null ? pageToCursor(nextPage) : undefined;\n\tif (synthesized != null) return { hasMore: true, cursor: synthesized, truncated: paged.truncated };\n\n\treturn { hasMore: false, cursor: undefined, truncated: true };\n}\n\n/**\n * Resolves the position a paged read reports as `page.currentPage`, per the single convention documented on\n * {@link ProviderPageInfo.currentPage}. Every paged read routes through here so the field means the same thing\n * on all of them: positional, never constant-1 for one read and positional for another.\n *\n * `providerPage` is what the provider (or the internal drain) established — 1 means \"nothing reported\".\n * `pageAdvanceable` is whether the read honors a page number at all: false for a cursor-only read, which\n * answers with its first page when handed a synthesized page-number cursor, so the requested `page` must NOT be\n * echoed there.\n */\nexport function resolveCurrentPage(options: {\n\tproviderPage: number;\n\trequestedPage: number;\n\tsuppliedCursor: string | undefined;\n\tpageAdvanceable: boolean;\n}): number {\n\tif (options.providerPage > 1) return options.providerPage;\n\t// A caller-threaded cursor DID advance the provider, so the caller's own position is authoritative for a\n\t// provider that reports none: prefer the page the cursor encodes, else the `page` supplied alongside it.\n\tif (options.suppliedCursor != null) return parsePageCursor(options.suppliedCursor) ?? options.requestedPage;\n\n\treturn options.pageAdvanceable ? options.requestedPage : 1;\n}\n\n/**\n * One page of a FLAT cursor-paged provider read — the shape both issue reads' providers return directly.\n *\n * `hasMore` is optional because one of the two providers leaves it off on a terminal page; absent reads as \"no\n * more\", which is what a provider that reported no continuation means.\n */\nexport interface FlatPage {\n\tcursor?: string;\n\thasMore?: boolean;\n\tpage?: number;\n\ttruncated: boolean;\n}\n\n/** What {@link drainFlatPagesToRequestedPage} established by walking. */\nexport interface FlatDrainResult<T extends FlatPage> {\n\t/** The requested page, or `undefined` when a page failed mid-walk (which also sets `fetchFailed`). */\n\tvalue: T | undefined;\n\t/** The position actually reached — 1 when nothing advanced. */\n\tcurrentPage: number;\n\ttruncated: boolean;\n\t/** True when the requested page is past the provider's last one, so it is genuinely EMPTY. */\n\trequestedPageMissing: boolean;\n\tfetchFailed: boolean;\n}\n\n/**\n * Walks a FLAT cursor-paged read forward to a requested page number, for a provider whose pages are\n * `{cursor, hasMore, page, truncated}` rather than the SDK's `PagedResult` wrapper.\n *\n * The sibling of {@link drainToRequestedPage}, not a replacement for it: that one normalizes SDK `paging` through\n * {@link toProviderPageInfo}, which retains only cursors whose JSON declares `type`/`cursors` — and the composite\n * cursor of a GitHub aliased search declares neither, so it would be dropped and the walk would never advance.\n * Two shapes genuinely need two entry points; what they must NOT have is two copies of the rules below, which is\n * what this exists to prevent (see this module's own note on drift).\n *\n * The rules, all of them subtle enough to be worth stating once:\n * - The empty-cursor sentinel is filtered, so a provider claiming another page without handing back a usable\n *   continuation is not re-read with `'{}'` (which it would answer with page 1 again).\n * - A provider that returns the SAME cursor isn't advancing: stop, and report the read as truncated rather than\n *   looping forever or publishing a short page as complete.\n * - A page requested past the provider's terminal cursor is that EMPTY page N — never the last available page\n *   relabeled, per {@link ProviderPageInfo.currentPage}.\n * - A page that fails mid-walk latches `fetchFailed` and leaves no value, so the caller can tell \"the read broke\"\n *   from \"the page was genuinely empty\".\n *\n * `fold` is the one thing the callers differ on — one merges SDK collection metadata across the walked pages, the\n * other keeps the largest reported match count — so it is a callback rather than a branch.\n */\nexport async function drainFlatPagesToRequestedPage<T extends FlatPage>(\n\tfirst: { value?: T; warning?: ProviderWarning },\n\toptions: {\n\t\trequestedPage: number;\n\t\tsuppliedCursor: string | undefined;\n\t\twarnings: ProviderWarning[];\n\t\treadPage: (cursor: string) => Promise<{ value?: T; warning?: ProviderWarning }>;\n\t\tfold?: (page: T) => void;\n\t},\n): Promise<FlatDrainResult<T>> {\n\tlet value = first.value;\n\tlet fetchFailed = first.warning != null && value == null;\n\tlet currentPage = value?.page ?? 1;\n\tlet truncated = value?.truncated ?? false;\n\n\tconst walkable = options.suppliedCursor == null && options.requestedPage > 1;\n\tif (walkable && value != null) {\n\t\tfor (\n\t\t\tlet nextCursor = usableCursor(value.cursor);\n\t\t\tcurrentPage < options.requestedPage && value.hasMore === true && nextCursor != null;\n\t\t\tnextCursor = usableCursor(value.cursor)\n\t\t) {\n\t\t\tconst next = await options.readPage(nextCursor);\n\t\t\tif (next.warning != null) {\n\t\t\t\tappendDedupedWarning(options.warnings, next.warning);\n\t\t\t}\n\t\t\tif (next.value == null) {\n\t\t\t\tfetchFailed = next.warning != null;\n\t\t\t\tvalue = undefined;\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tvalue = next.value;\n\t\t\ttruncated = truncated || value.truncated;\n\t\t\toptions.fold?.(value);\n\t\t\tcurrentPage = value.page ?? currentPage + 1;\n\t\t\tif (usableCursor(value.cursor) === nextCursor) {\n\t\t\t\ttruncated = true;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn {\n\t\tvalue: value,\n\t\tcurrentPage: currentPage,\n\t\ttruncated: truncated,\n\t\t// Every case reduces to \"a page was asked for by number and the walk fell short\", including the one where\n\t\t// no walk ran at all because the first page was already terminal.\n\t\trequestedPageMissing: walkable && currentPage < options.requestedPage,\n\t\tfetchFailed: fetchFailed,\n\t};\n}\n\n/** The mutable state {@link drainToRequestedPage} carries across the pages it walks. */\nexport interface DrainState<T> {\n\titems: T[];\n\tpaged: NormalizedPage;\n\tmetadata: CollectionMetadata | undefined;\n\tfetchFailed: boolean;\n}\n\n/**\n * Advances a cursor-only read to the requested page when the caller supplied only `page`.\n *\n * A cursor-only read accepts a synthesized page-number cursor and ignores it, answering with its first page, so\n * the requested page has to be reached by walking the provider's own opaque continuations. Only the last\n * successfully-read page's items are kept — returning pages 1..N as \"page N\" would duplicate items for a normal\n * paged consumer — while warnings and metadata are merged across the whole drained prefix.\n *\n * Shared by the repo-scoped and account-wide PR reads and the repo-scoped issue read so the three cannot drift:\n * a requested page past the provider's terminal cursor is an EMPTY page N on all of them, per\n * {@link ProviderPageInfo.currentPage}, never the last available page relabeled.\n */\nexport async function drainToRequestedPage<T>(\n\tstate: DrainState<T>,\n\toptions: {\n\t\trequestedPage: number;\n\t\titemsPerPage: number | undefined;\n\t\twarnings: ProviderWarning[];\n\t\treadPage: (cursor: string) => Promise<{\n\t\t\tvalue?: (PagedResult<T> & { metadata?: CollectionMetadata }) | undefined;\n\t\t\twarning?: ProviderWarning;\n\t\t}>;\n\t},\n): Promise<DrainState<T>> {\n\tlet { items, metadata, fetchFailed } = state;\n\tlet currentPage = 1;\n\tlet currentCursor = usableCursor(state.paged.hasMore ? state.paged.cursor : undefined);\n\tlet currentHasMore = state.paged.hasMore && currentCursor != null;\n\tlet currentTruncated = state.paged.truncated;\n\t// A page requested past the terminal cursor is that empty page N. Distinguished from the first read\n\t// having failed outright, which is already reported as page N with no items by the caller's own state.\n\tconst missRequestedPage = () => {\n\t\titems = [];\n\t\tcurrentPage = options.requestedPage;\n\t\tcurrentCursor = undefined;\n\t\tcurrentHasMore = false;\n\t};\n\n\tif (fetchFailed) {\n\t\tmissRequestedPage();\n\t}\n\n\twhile (currentPage < options.requestedPage && currentHasMore && currentCursor != null) {\n\t\tconst { value, warning } = await options.readPage(currentCursor);\n\t\tif (warning != null) {\n\t\t\tappendDedupedWarning(options.warnings, warning);\n\t\t}\n\t\tif (value == null) {\n\t\t\tfetchFailed = true;\n\t\t\tmissRequestedPage();\n\t\t\tbreak;\n\t\t}\n\n\t\titems = value.values;\n\t\tmetadata = mergeCollectionMetadata(metadata, value.metadata);\n\t\tconst next = toProviderPageInfo(options.itemsPerPage ?? value.values.length, value.paging);\n\t\tcurrentPage++;\n\t\tcurrentTruncated ||= next.truncated;\n\t\tconst nextCursor = usableCursor(next.cursor);\n\t\t// A provider that hands back the same cursor (or none) isn't advancing; stop rather than refetch\n\t\t// the same page forever.\n\t\tif (nextCursor == null || nextCursor === currentCursor) {\n\t\t\tcurrentCursor = undefined;\n\t\t\tcurrentHasMore = false;\n\t\t\tbreak;\n\t\t}\n\n\t\tcurrentCursor = nextCursor;\n\t\tcurrentHasMore = next.hasMore;\n\t}\n\n\tif (currentPage < options.requestedPage) {\n\t\tmissRequestedPage();\n\t}\n\n\treturn {\n\t\titems: items,\n\t\tpaged: {\n\t\t\tpage: { currentPage: currentPage, itemsPerPage: options.itemsPerPage ?? items.length },\n\t\t\thasMore: currentHasMore,\n\t\t\tcursor: currentCursor,\n\t\t\ttruncated: currentTruncated,\n\t\t},\n\t\tmetadata: metadata,\n\t\tfetchFailed: fetchFailed,\n\t};\n}\n"],"mappings":"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"}