@mdbase-dev/connect 0.1.0-beta.70 → 0.1.0-beta.75

package/dist/browser/mdbase-connect.min.js.sha384

@@ -1 +1 @@
-sha384-AgV4nZxZSfEm0hxmoY/+laBu7GgQk24V8nJDEn4mFCtAMItb3v+XH40zTftyTkjY
+sha384-2NXwGD96iZvxt5iZ6vfV4ZTuoY3PG7RMPOn+wmXEq+K+i06SN/u0vdHtOUb+Mj2p

package/dist/collection-client.d.ts

@@ -1,6 +1,6 @@
 import type { CollectionOperation, CollectionTypeDocument, JsonObject } from "@mdbase-dev/connect-protocol";
 import { type CollectionChangesProblemCode, type CollectionDescriptionProblemCode, type CollectionMutationProblemCode, type CollectionQueryProblemCode, type CollectionReadProblemCode, type CollectionTypeProblemCode, type ConnectOutcome } from "./outcomes.js";
-import type { ChangesInput, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, AssessCollectionSetupInput, AssessTypePackInput, ApplyCollectionSetupInput, ApplyTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseCollectionTransport, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameResult, RecordDocument, SavedViewExecution, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, WatchOptions } from "./operation-types.js";
+import type { ChangesInput, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, AssessCollectionSetupInput, AssessTypePackInput, ApplyCollectionSetupInput, ApplyTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseCollectionTransport, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameResult, RecordDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, WatchOptions } from "./operation-types.js";
 /**
  * Typed collection operations independent of OAuth, HTTP, or storage.
  *
@@ -20,6 +20,7 @@ export declare class MdbaseCollectionClient<Frontmatter extends JsonObject = Jso
     queryAll(input?: QueryInput, options?: QueryAllOptions<Frontmatter>): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
     listViews(options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewList, CollectionReadProblemCode>>;
     executeView(input: ExecuteViewInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewExecution<Frontmatter>, CollectionReadProblemCode>>;
+    executeViewPages(input: ExecuteViewInput, options?: SavedViewPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<SavedViewPage<Frontmatter>, CollectionReadProblemCode>>;
     readViewSource(input: ReadViewSourceInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionReadProblemCode>>;
     createViewSource(input: CreateViewSourceInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionMutationProblemCode>>;
     updateViewSource(input: UpdateViewSourceInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionMutationProblemCode>>;

package/dist/collection-client.js

@@ -1,5 +1,6 @@
 import { abortableDelay } from "./async.js";
 import { coordinatedQueryPages } from "./query-pagination.js";
+import { coordinatedSavedViewPages } from "./saved-view-pagination.js";
 import { MdbaseConnectError, connectError, connectProblem, operationProblem } from "./errors.js";
 import { COLLECTION_CHANGES_PROBLEM_CODES, COLLECTION_DESCRIPTION_PROBLEM_CODES, COLLECTION_MUTATION_PROBLEM_CODES, COLLECTION_QUERY_PROBLEM_CODES, COLLECTION_READ_PROBLEM_CODES, COLLECTION_TYPE_PROBLEM_CODES, ALL_CONNECT_PROBLEM_CODES, captureConnectOutcome, connectFailure, connectSuccess } from "./outcomes.js";
 import { createRequestBudget, DEFAULT_REQUEST_TIMEOUT_MS, requestAbortReason } from "./request-budget.js";
@@ -38,7 +39,10 @@ export class MdbaseCollectionClient {
             results: results.map(wireQueryRecord),
             ...(meta ? {
                 meta: {
-                    totalCount: meta.total_count,
+                    ...(typeof meta.total_count === "number" ? { totalCount: meta.total_count } : {}),
+                    ...(meta.total_count_outcome === undefined
+                        ? {}
+                        : { totalCountOutcome: meta.total_count_outcome }),
                     hasMore: meta.has_more,
                     ...(meta.cursor ? { cursor: meta.cursor } : {}),
                     ...(meta.snapshot ? { snapshot: meta.snapshot } : {})
@@ -99,6 +103,9 @@ export class MdbaseCollectionClient {
         const outcome = await this.envelopeOperation("execute_view", input, COLLECTION_READ_PROBLEM_CODES, options);
         return mapOutcome(outcome, wireSavedViewExecution);
     }
+    async *executeViewPages(input, options = {}) {
+        yield* coordinatedSavedViewPages((pageInput, pageOptions) => this.executeView(pageInput, pageOptions), (cursor) => this.releaseQueryCursor(cursor), input, options);
+    }
     readViewSource(input, options) {
         return this.envelopeOperation("read_view_source", input, COLLECTION_READ_PROBLEM_CODES, options);
     }
@@ -530,6 +537,7 @@ function wireSavedViewExecution(value) {
         meta: {
             totalCount: value.meta.total_count,
             hasMore: value.meta.has_more,
+            ...(value.meta.cursor ? { cursor: value.meta.cursor } : {}),
             view: value.meta.view,
             ...(value.meta.context ? { context: value.meta.context } : {}),
             ...(value.meta.groups ? { groups: value.meta.groups } : {})

package/dist/connection.d.ts

@@ -5,7 +5,7 @@ import type { GrantKeyStore } from "./crypto.js";
 import { MdbaseFileClient } from "./files.js";
 import { type Application } from "./internal-types.js";
 import type { MdbaseNativeNotificationRegistration, MdbaseNativeNotificationRegistrationOptions, MdbaseNotificationRegistration, MdbaseNotificationRegistrationOptions } from "./notifications.js";
-import type { ChangesInput, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, ApplyCollectionSetupInput, ApplyTypePackInput, AssessCollectionSetupInput, AssessTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteProgressOptions, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, PendingMutation, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameProgressOptions, RenameResult, RecordDocument, SavedViewExecution, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, MdbaseWatchSubscription, WatchInput } from "./operation-types.js";
+import type { ChangesInput, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, ApplyCollectionSetupInput, ApplyTypePackInput, AssessCollectionSetupInput, AssessTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteProgressOptions, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, PendingMutation, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameProgressOptions, RenameResult, RecordDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, MdbaseWatchSubscription, WatchInput } from "./operation-types.js";
 import { type AuthorizationProblemCode, type CollectionChangesProblemCode, type CollectionDescriptionProblemCode, type CollectionMutationProblemCode, type CollectionQueryProblemCode, type CollectionReadProblemCode, type CollectionTypeProblemCode, type ConnectOutcome, type DirectAccessProblemCode, type NotificationProblemCode, type RegistrationProblemCode } from "./outcomes.js";
 import type { MdbaseDeviceAuthorization } from "./authorization-types.js";
 import { type ResolvedConnectTimeouts } from "./request-budget.js";
@@ -112,6 +112,7 @@ export declare class MdbaseConnection<Frontmatter extends JsonObject = JsonObjec
     queryAll(input?: QueryInput, options?: QueryAllOptions<Frontmatter>): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
     listViews(options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewList, CollectionReadProblemCode>>;
     executeView(input: ExecuteViewInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewExecution<Frontmatter>, CollectionReadProblemCode>>;
+    executeViewPages(input: ExecuteViewInput, options?: SavedViewPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<SavedViewPage<Frontmatter>, CollectionReadProblemCode>>;
     readViewSource(input: ReadViewSourceInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionReadProblemCode>>;
     createViewSource(input: CreateViewSourceInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionMutationProblemCode>>;
     updateViewSource(input: UpdateViewSourceInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionMutationProblemCode>>;

package/dist/connection.js

@@ -237,6 +237,9 @@ export class MdbaseConnection {
     executeView(input, options) {
         return this.collectionClient.executeView(input, options);
     }
+    executeViewPages(input, options = {}) {
+        return this.collectionClient.executeViewPages(input, options);
+    }
     readViewSource(input, options) {
         return this.collectionClient.readViewSource(input, options);
     }

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export type { MdbaseFileSource, CollectionFileDescriptor, MdbaseFileDeleteReceip
 export { parseMdbasePushPayload, parseMdbaseNativeNotificationData, showMdbasePushNotification } from "./notifications.js";
 export type { MdbaseNotificationRegistrationOptions, MdbaseNotificationRegistration, MdbaseNativeNotificationRegistrationOptions, MdbaseNativeNotificationRegistration, MdbaseNativeNotificationData, MdbasePushPayload } from "./notifications.js";
 export type { ConnectSuccess, ConnectFailure, ConnectOutcome, CommonOperationProblemCode, RegistrationProblemCode, AuthorizationProblemCode, NotificationProblemCode, DirectAccessProblemCode, SessionProblemCode, CollectionSetupProblemCode, CollectionDescriptionProblemCode, CollectionReadProblemCode, CollectionQueryProblemCode, CollectionMutationProblemCode, CollectionChangesProblemCode, CollectionTypeProblemCode } from "./outcomes.js";
-export type { MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ReadInput, DataContractSelector, CollectionFileMetadata, DataContractViewIdentity, QueryRecord, RecordDocument, QueryInput, QueryProjection, QuerySelectionExpression, QueryOrder, QuerySummary, QueryResult, QueryPagesOptions, QueryAllOptions, QueryPage, ConnectRequestOptions, MutationEstimate, MutationProgressState, MutationProgress, MutationProgressOptions, RequestCoordinationOptions, RenameProgressOptions, DeleteProgressOptions, PendingMutationSummary, PendingMutation, CreateInput, UpdateInput, DeleteInput, DeleteResult, DeletePreflightResult, RenameInput, RenameResult, RenamePreflightResult, ReadTypeInput, CreateTypeInput, UpdateTypeInput, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, SavedViewPresentation, SavedViewSource, SavedViewProperty, SavedNamedView, SavedViewDocument, SavedViewList, SavedViewSourceDocument, SavedViewExecution, ContractSetupChoice, TypePackResourceDiff, TypePackReceipt, TypePackAssessment, TypePackApplyResult, ConfigurationContributionValue, ConfigurationRequirement, ConfigurationProvision, ApplicationCollectionSetupRequirements, ApplicationCollectionSetupProvisions, ConfigurationSetupConflict, ConfigurationSetupAssessment, CollectionSetupAssessment, CollectionSetupReceipt, CollectionSetupApplyResult, AssessTypePackInput, ApplyTypePackInput, AssessCollectionSetupInput, ApplyCollectionSetupInput, ChangesInput, WatchOptions, WatchRetryOptions, WatchStatus, WatchInput, MdbaseWatchSubscription, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionContractDescriptor, CollectionContractImplementationDescriptor, CollectionTypeDescriptor } from "./operation-types.js";
+export type { MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ReadInput, DataContractSelector, CollectionFileMetadata, DataContractViewIdentity, QueryRecord, RecordDocument, QueryInput, QueryProjection, QuerySelectionExpression, QueryOrder, QuerySummary, QueryResult, QueryPagesOptions, QueryAllOptions, QueryPage, ConnectRequestOptions, MutationEstimate, MutationProgressState, MutationProgress, MutationProgressOptions, RequestCoordinationOptions, RenameProgressOptions, DeleteProgressOptions, PendingMutationSummary, PendingMutation, CreateInput, UpdateInput, DeleteInput, DeleteResult, DeletePreflightResult, RenameInput, RenameResult, RenamePreflightResult, ReadTypeInput, CreateTypeInput, UpdateTypeInput, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, SavedViewPresentation, SavedViewSource, SavedViewProperty, SavedNamedView, SavedViewDocument, SavedViewList, SavedViewSourceDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, ContractSetupChoice, TypePackResourceDiff, TypePackReceipt, TypePackAssessment, TypePackApplyResult, ConfigurationContributionValue, ConfigurationRequirement, ConfigurationProvision, ApplicationCollectionSetupRequirements, ApplicationCollectionSetupProvisions, ConfigurationSetupConflict, ConfigurationSetupAssessment, CollectionSetupAssessment, CollectionSetupReceipt, CollectionSetupApplyResult, AssessTypePackInput, ApplyTypePackInput, AssessCollectionSetupInput, ApplyCollectionSetupInput, ChangesInput, WatchOptions, WatchRetryOptions, WatchStatus, WatchInput, MdbaseWatchSubscription, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionContractDescriptor, CollectionContractImplementationDescriptor, CollectionTypeDescriptor } from "./operation-types.js";
 export { externalStore } from "./external-store.js";
 export type { MdbaseExternalStore } from "./external-store.js";
 export { MdbaseBrowserSelection, MdbaseMemorySelection } from "./selection.js";

package/dist/operation-types.d.ts

@@ -172,7 +172,14 @@ export interface QueryInput {
 export interface QueryResult<Record extends JsonObject = JsonObject> {
     results: Array<QueryRecord<Record>>;
     meta?: {
-        totalCount: number;
+        /** Exact total when it is available within the page summary budget. */
+        totalCount?: number;
+        /** Typed successful outcome when exact counting is deferred for paging. */
+        totalCountOutcome?: {
+            status: "deferred";
+            budget: "eager_summary_rows";
+            limit: number;
+        };
         hasMore: boolean;
         cursor?: string;
         snapshot?: string;
@@ -385,8 +392,19 @@ export interface ExecuteViewInput {
     } | null;
     limit?: number;
     offset?: number;
+    /** Opaque, single-use token returned for the next snapshot-pinned page. */
+    cursor?: string;
     render?: boolean;
 }
+export interface SavedViewPagesOptions<Frontmatter extends JsonObject = JsonObject> {
+    firstPageSize?: number;
+    pageSize?: number;
+    signal?: AbortSignal;
+    /** Independent budget for each page requested by this caller-driven iterator. */
+    pageTimeoutMs?: number | null;
+    coordination?: RequestCoordinationOptions;
+    onProgress?: (page: SavedViewPage<Frontmatter>) => void;
+}
 export interface SavedViewPresentation extends JsonObject {
     type: string;
     fallback?: string;
@@ -439,6 +457,7 @@ export interface SavedViewExecution<Frontmatter extends JsonObject = JsonObject>
     meta: {
         totalCount: number;
         hasMore: boolean;
+        cursor?: string;
         view: {
             path: string;
             id: string;
@@ -453,6 +472,14 @@ export interface SavedViewExecution<Frontmatter extends JsonObject = JsonObject>
         }>;
     };
 }
+export interface SavedViewPage<Frontmatter extends JsonObject = JsonObject> extends SavedViewExecution<Frontmatter> {
+    page: number;
+    offset: number;
+    loaded: number;
+    complete: boolean;
+    /** Opaque token for the next page while this iterator remains open. */
+    cursor?: string;
+}
 export type ContractSetupChoice = {
     contract: ContractRequirement;
     mode: "starter";

package/dist/saved-view-pagination.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import { type CollectionReadProblemCode, type ConnectOutcome } from "./outcomes.js";
+import type { ConnectRequestOptions, ExecuteViewInput, SavedViewExecution, SavedViewPage, SavedViewPagesOptions } from "./operation-types.js";
+type SavedViewOperation<Frontmatter extends JsonObject> = (input: ExecuteViewInput, options?: ConnectRequestOptions) => Promise<ConnectOutcome<SavedViewExecution<Frontmatter>, CollectionReadProblemCode>>;
+export declare function coordinatedSavedViewPages<Frontmatter extends JsonObject>(executeView: SavedViewOperation<Frontmatter>, releaseQueryCursor: (cursor: string) => Promise<void>, input: ExecuteViewInput, options?: SavedViewPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<SavedViewPage<Frontmatter>, CollectionReadProblemCode>>;
+export {};

package/dist/saved-view-pagination.js

@@ -0,0 +1,76 @@
+import { connectProblem } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+export async function* coordinatedSavedViewPages(executeView, releaseQueryCursor, input, options = {}) {
+    const { offset: requestedOffset, limit: requestedLimit, cursor: requestedCursor, ...criteria } = input;
+    let offset = nonNegativeInteger(requestedOffset, 0);
+    const firstPageSize = positiveInteger(options.firstPageSize ?? requestedLimit, 200);
+    const pageSize = positiveInteger(options.pageSize ?? requestedLimit, 1_000);
+    let cursor = requestedCursor;
+    let cursorMode = requestedCursor !== undefined;
+    let cursorToRelease = requestedCursor;
+    let loaded = 0;
+    let pageNumber = 0;
+    try {
+        while (!options.signal?.aborted) {
+            const pageCursor = cursor;
+            const outcome = await executeView({
+                ...criteria,
+                limit: pageNumber === 0 ? firstPageSize : pageSize,
+                ...(cursorMode && pageCursor ? { cursor: pageCursor } : { offset })
+            }, {
+                signal: options.signal,
+                timeoutMs: options.pageTimeoutMs,
+                coordination: { ...options.coordination, coalesce: false }
+            });
+            if (!outcome.ok) {
+                yield outcome;
+                return;
+            }
+            const result = outcome.value;
+            const returnedCursor = result.meta.cursor;
+            if (returnedCursor) {
+                cursorMode = true;
+                cursor = returnedCursor;
+                cursorToRelease = returnedCursor;
+            }
+            else if (cursorMode) {
+                cursor = undefined;
+                cursorToRelease = pageCursor;
+            }
+            if (cursorMode && result.meta.hasMore && !returnedCursor) {
+                yield connectFailure(connectProblem("invalid_operation_response", "The collection authority omitted the cursor required for the next saved-view page."));
+                return;
+            }
+            loaded += result.results.length;
+            const complete = !result.meta.hasMore || result.results.length === 0;
+            const page = {
+                ...result,
+                page: pageNumber,
+                offset,
+                loaded,
+                complete,
+                ...(returnedCursor ? { cursor: returnedCursor } : {})
+            };
+            options.onProgress?.(page);
+            yield connectSuccess(page, outcome.diagnostics);
+            if (complete)
+                return;
+            offset += result.results.length;
+            pageNumber += 1;
+        }
+    }
+    finally {
+        if (cursorMode && cursorToRelease)
+            await releaseQueryCursor(cursorToRelease);
+    }
+}
+function nonNegativeInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : fallback;
+}
+function positiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect",
-  "version": "0.1.0-beta.70",
+  "version": "0.1.0-beta.75",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mdbase-dev/connect-protocol": "0.1.0-beta.70"
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.75"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",