@mdbase-dev/connect 0.1.0-beta.64 → 0.1.0-beta.66

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

@@ -1 +1 @@
-sha384-lle3e5SEN8S45RwEaaerEa1VKEBzMw7JZGQcuO1VI734WP7P95QHHR5DbXASXaaL
+sha384-Sac9rFWvetnHV52bEp32Rc1ljfJn2zHX+iQ7rHGKCRRAsiaeaofsdMp2IskpKr4N

package/dist/collection-client.d.ts

@@ -60,5 +60,6 @@ export declare class MdbaseCollectionClient<Frontmatter extends JsonObject = Jso
     }, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseTimerReconciliation, CollectionMutationProblemCode>>;
     watch(options?: WatchOptions): AsyncGenerator<ConnectOutcome<CollectionChange, CollectionChangesProblemCode>>;
     private rawOperation;
+    private releaseQueryCursor;
     private envelopeOperation;
 }

package/dist/collection-client.js

@@ -1,4 +1,5 @@
 import { abortableDelay } from "./async.js";
+import { coordinatedQueryPages } from "./query-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";
@@ -39,56 +40,14 @@ export class MdbaseCollectionClient {
                 meta: {
                     totalCount: meta.total_count,
                     hasMore: meta.has_more,
+                    ...(meta.cursor ? { cursor: meta.cursor } : {}),
                     ...(meta.snapshot ? { snapshot: meta.snapshot } : {})
                 }
             } : {})
         }));
     }
     async *queryPages(input = {}, options = {}) {
-        const { offset: requestedOffset, limit: requestedLimit, snapshot: requestedSnapshot, ...criteria } = input;
-        let offset = nonNegativeInteger(requestedOffset, 0);
-        const firstPageSize = positiveInteger(options.firstPageSize ?? requestedLimit, 200);
-        const pageSize = positiveInteger(options.pageSize ?? requestedLimit, 1_000);
-        let snapshot = requestedSnapshot;
-        let loaded = 0;
-        let pageNumber = 0;
-        while (!options.signal?.aborted) {
-            const queried = await this.query({
-                ...criteria,
-                offset,
-                limit: pageNumber === 0 ? firstPageSize : pageSize,
-                ...(snapshot ? { snapshot } : {})
-            }, { signal: options.signal, timeoutMs: options.pageTimeoutMs });
-            if (!queried.ok) {
-                yield queried;
-                return;
-            }
-            const result = queried.value;
-            const returnedSnapshot = result.meta?.snapshot;
-            if (snapshot && returnedSnapshot && snapshot !== returnedSnapshot) {
-                yield connectFailure(connectProblem("query_snapshot_changed", "The collection query snapshot changed while paging. Refresh the query before continuing."));
-                return;
-            }
-            if (!snapshot && returnedSnapshot)
-                snapshot = returnedSnapshot;
-            loaded += result.results.length;
-            const complete = !result.meta?.hasMore || result.results.length === 0;
-            const page = {
-                results: result.results,
-                ...(result.meta ? { meta: result.meta } : {}),
-                page: pageNumber,
-                offset,
-                loaded,
-                complete,
-                ...(snapshot ? { snapshot } : {})
-            };
-            options.onProgress?.(page);
-            yield connectSuccess(page, queried.diagnostics);
-            if (complete)
-                return;
-            offset += result.results.length;
-            pageNumber += 1;
-        }
+        yield* coordinatedQueryPages((pageInput, pageOptions) => this.query(pageInput, pageOptions), (cursor) => this.releaseQueryCursor(cursor), input, options);
     }
     async queryAll(input = {}, options = {}) {
         const budget = createRequestBudget(options, this.requestTimeoutMs);
@@ -101,6 +60,7 @@ export class MdbaseCollectionClient {
                 pageSize: options.pageSize,
                 signal: budget.signal,
                 pageTimeoutMs: null,
+                coordination: options.coordination,
                 onProgress: options.onProgress
             })) {
                 if (!outcome.ok)
@@ -115,7 +75,6 @@ export class MdbaseCollectionClient {
             return connectSuccess({
                 results,
                 meta: {
-                    ...(finalPage?.meta ?? {}),
                     totalCount: finalPage?.meta?.totalCount ?? results.length,
                     hasMore: finalPage ? !finalPage.complete : false,
                     ...(finalPage?.snapshot ? { snapshot: finalPage.snapshot } : {})
@@ -317,6 +276,14 @@ export class MdbaseCollectionClient {
     rawOperation(operation, input, allowedCodes, options) {
         return captureConnectOutcome(() => this.transport.operation(operation, input, options), allowedCodes);
     }
+    async releaseQueryCursor(cursor) {
+        try {
+            await this.envelopeOperation("query", { release_cursor: cursor }, COLLECTION_QUERY_PROBLEM_CODES, { timeoutMs: 2_000, coordination: { coalesce: false } });
+        }
+        catch {
+            // Lease expiry is bounded by the authority; cleanup never masks query results.
+        }
+    }
     async envelopeOperation(operation, input, allowedCodes, options) {
         const transported = await captureConnectOutcome(() => this.transport.operation(operation, input, options), allowedCodes);
         if (!transported.ok)
@@ -371,6 +338,8 @@ function wireQueryInput(input) {
         ...(input.summaries ? { summaries: input.summaries } : {}),
         ...(input.limit === undefined ? {} : { limit: input.limit }),
         ...(input.offset === undefined ? {} : { offset: input.offset }),
+        ...(input.pagination ? { pagination: input.pagination } : {}),
+        ...(input.cursor ? { cursor: input.cursor } : {}),
         ...(input.snapshot ? { snapshot: input.snapshot } : {}),
         ...(input.includeBody === undefined ? {} : { include_body: input.includeBody }),
         ...(input.frontmatterMode ? { frontmatter_mode: input.frontmatterMode } : {}),
@@ -707,9 +676,3 @@ function wireCollectionDescription(value) {
         ...(value.configuration ? { configuration: value.configuration } : {})
     };
 }
-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/dist/connection.js

@@ -7,6 +7,7 @@ import { DEFAULT_OPERATIONS } from "./internal-types.js";
 import { assertDeletePreview, assertRenamePreview, deleteEstimate, isCancellation, renameEstimate, throwIfCancelled, uniqueOperations } from "./operation-helpers.js";
 import { AUTHORIZATION_PROBLEM_CODES, COLLECTION_CHANGES_PROBLEM_CODES, COLLECTION_MUTATION_PROBLEM_CODES, DIRECT_ACCESS_PROBLEM_CODES, NOTIFICATION_PROBLEM_CODES, REGISTRATION_PROBLEM_CODES, captureConnectOutcome, connectFailure, connectSuccess } from "./outcomes.js";
 import { withCooperativeRequestBudget, withRequestBudget } from "./request-budget.js";
+import { CollectionRequestCoordinator } from "./request-coordinator.js";
 export class MdbaseConnection {
     internals;
     collectionId;
@@ -35,9 +36,9 @@ export class MdbaseConnection {
         }, {
             downloadPart: (session, partIndex, expectedLength, signal) => this.transport.files.downloadHostedPart(session, partIndex, expectedLength, signal)
         }, internals.timeouts);
-        this.collectionClient = new MdbaseCollectionClient({
+        this.collectionClient = new MdbaseCollectionClient(new CollectionRequestCoordinator({
             operation: (operation, input, requestOptions) => this.transport.performOperation(operation, input, requestOptions)
-        }, internals.timeouts.requestMs);
+        }, internals.timeouts.requestMs), internals.timeouts.requestMs);
         this.notifications = new ConnectionNotifications({
             serverUrl: internals.serverUrl,
             storage: internals.storage,

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, 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, 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

@@ -158,7 +158,11 @@ export interface QueryInput {
     summaries?: QuerySummary[];
     limit?: number;
     offset?: number;
-    /** Opaque token returned by the first metadata page for consistent, fast pagination. */
+    /** Request generation-pinned cursor pagination from a supporting authority. */
+    pagination?: "cursor";
+    /** Opaque, single-use token returned for the next generation-pinned page. */
+    cursor?: string;
+    /** Legacy stable-query token used by older authorities. */
     snapshot?: string;
     includeBody?: boolean;
     frontmatterMode?: "effective" | "persisted" | "both";
@@ -170,6 +174,7 @@ export interface QueryResult<Record extends JsonObject = JsonObject> {
     meta?: {
         totalCount: number;
         hasMore: boolean;
+        cursor?: string;
         snapshot?: string;
     };
 }
@@ -179,6 +184,7 @@ export interface QueryPagesOptions<Record extends JsonObject = JsonObject> {
     signal?: AbortSignal;
     /** Independent budget for each page requested by this caller-driven iterator. */
     pageTimeoutMs?: number | null;
+    coordination?: RequestCoordinationOptions;
     onProgress?: (page: QueryPage<Record>) => void;
 }
 export interface QueryAllOptions<Record extends JsonObject = JsonObject> extends ConnectRequestOptions {
@@ -193,12 +199,27 @@ export interface QueryPage<Record extends JsonObject = JsonObject> {
     offset: number;
     loaded: number;
     complete: boolean;
+    /** Opaque token for the next page while this iterator remains open. */
+    cursor?: string;
     snapshot?: string;
 }
 export interface ConnectRequestOptions {
     signal?: AbortSignal;
     /** Relative request budget. `null` deliberately disables the SDK default. */
     timeoutMs?: number | null;
+    /** Optional coordination for replaceable reads on this selected connection. */
+    coordination?: RequestCoordinationOptions;
+}
+export interface RequestCoordinationOptions {
+    /**
+     * Stable UI/request family. Required when `latestWins` is enabled; a newer
+     * request in the same family cancels the older read or query.
+     */
+    family?: string;
+    /** Explicitly cancel older work in this family. Mutations never allow this. */
+    latestWins?: boolean;
+    /** Disable automatic coalescing of identical signal-free reads. */
+    coalesce?: boolean;
 }
 export interface MutationEstimate {
     /** Records whose links may be affected, excluding the record being mutated. */

package/dist/outcomes.d.ts

@@ -29,14 +29,14 @@ export declare const SESSION_PROBLEM_CODES: readonly ["discovery_failed", "inval
 export type CollectionSetupProblemCode = "collection_configuration_invalid" | "collection_invalid" | "collection_type_registry_invalid" | "collection_version_unsupported";
 export type CollectionDescriptionProblemCode = CommonOperationProblemCode | CollectionSetupProblemCode;
 export type CollectionReadProblemCode = CollectionDescriptionProblemCode | "invalid_path" | "operation_invalid";
-export type CollectionQueryProblemCode = CollectionReadProblemCode | "query_snapshot_changed" | "sandbox_unsupported";
+export type CollectionQueryProblemCode = CollectionReadProblemCode | "cursor_capacity_exhausted" | "generation_expired" | "invalid_read_cursor" | "query_snapshot_changed" | "sandbox_unsupported";
 export type CollectionMutationProblemCode = CollectionReadProblemCode | "concurrent_modification" | "invalid_preflight" | "pending_mutation_unresolved";
 export type CollectionChangesProblemCode = CollectionDescriptionProblemCode | "change_cursor_reset";
 export type CollectionTypeProblemCode = CollectionMutationProblemCode | "type_pack_provision_failed";
 export declare const COLLECTION_SETUP_PROBLEM_CODES: readonly ["collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported"];
 export declare const COLLECTION_DESCRIPTION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported"];
 export declare const COLLECTION_READ_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid"];
-export declare const COLLECTION_QUERY_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "query_snapshot_changed", "sandbox_unsupported"];
+export declare const COLLECTION_QUERY_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "cursor_capacity_exhausted", "generation_expired", "invalid_read_cursor", "query_snapshot_changed", "sandbox_unsupported"];
 export declare const COLLECTION_MUTATION_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "concurrent_modification", "invalid_preflight", "pending_mutation_unresolved"];
 export declare const COLLECTION_CHANGES_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "change_cursor_reset"];
 export declare const COLLECTION_TYPE_PROBLEM_CODES: readonly ["access_denied", "access_paused", "authorization_binding_incompatible", "authorization_expired", "capability_contract_incompatible", "collection_access_denied", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "direct_operation_rejected", "durable_mutation_unsupported", "operation_outcome_unknown", "encryption_required", "encrypted_relay_rejected", "hosted_provider_unavailable", "insufficient_access", "invalid_encrypted_response", "invalid_operation_response", "invalid_request", "missing_grant_key", "mutation_recovery_expired", "mutation_request_conflict", "not_authorized", "operation_cancelled", "operation_failed", "rate_limited", "relay_authorization_expired", "relay_unavailable", "temporarily_unavailable", "timeout", "transport_protocol_incompatible", "unsupported_operation", "collection_configuration_invalid", "collection_invalid", "collection_type_registry_invalid", "collection_version_unsupported", "invalid_path", "operation_invalid", "concurrent_modification", "invalid_preflight", "pending_mutation_unresolved", "type_pack_provision_failed"];

package/dist/outcomes.js

@@ -127,6 +127,9 @@ export const COLLECTION_READ_PROBLEM_CODES = [
 ];
 export const COLLECTION_QUERY_PROBLEM_CODES = [
     ...COLLECTION_READ_PROBLEM_CODES,
+    "cursor_capacity_exhausted",
+    "generation_expired",
+    "invalid_read_cursor",
     "query_snapshot_changed",
     "sandbox_unsupported"
 ];

package/dist/query-pagination.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import { type CollectionQueryProblemCode, type ConnectOutcome } from "./outcomes.js";
+import type { ConnectRequestOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult } from "./operation-types.js";
+type QueryOperation<Frontmatter extends JsonObject> = (input: QueryInput, options?: ConnectRequestOptions) => Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
+export declare function coordinatedQueryPages<Frontmatter extends JsonObject>(query: QueryOperation<Frontmatter>, releaseQueryCursor: (cursor: string) => Promise<void>, input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<QueryPage<Frontmatter>, CollectionQueryProblemCode>>;
+export {};

package/dist/query-pagination.js

@@ -0,0 +1,98 @@
+import { connectProblem } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+export async function* coordinatedQueryPages(query, releaseQueryCursor, input = {}, options = {}) {
+    const { offset: requestedOffset, limit: requestedLimit, cursor: requestedCursor, pagination: requestedPagination, snapshot: requestedSnapshot, ...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 snapshot = requestedSnapshot;
+    let loaded = 0;
+    let pageNumber = 0;
+    try {
+        while (!options.signal?.aborted) {
+            const pageCursor = cursor;
+            const queried = await query({
+                ...criteria,
+                limit: pageNumber === 0 ? firstPageSize : pageSize,
+                ...(cursorMode
+                    ? (pageCursor ? { cursor: pageCursor } : { pagination: "cursor" })
+                    : {
+                        offset,
+                        ...(snapshot ? { snapshot } : {}),
+                        ...(!snapshot && requestedPagination === "cursor"
+                            ? { pagination: "cursor" }
+                            : {})
+                    }),
+                ...(!cursorMode && !snapshot && requestedPagination === undefined
+                    ? { pagination: "cursor" }
+                    : {})
+            }, {
+                signal: options.signal,
+                timeoutMs: options.pageTimeoutMs,
+                coordination: { ...options.coordination, coalesce: false }
+            });
+            if (!queried.ok) {
+                yield queried;
+                return;
+            }
+            const result = queried.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 query page."));
+                return;
+            }
+            const returnedSnapshot = result.meta?.snapshot;
+            if (!cursorMode && snapshot && returnedSnapshot && snapshot !== returnedSnapshot) {
+                yield connectFailure(connectProblem("query_snapshot_changed", "The collection query snapshot changed while paging. Refresh the query before continuing."));
+                return;
+            }
+            if (!cursorMode && !snapshot && returnedSnapshot)
+                snapshot = returnedSnapshot;
+            loaded += result.results.length;
+            const complete = !result.meta?.hasMore || result.results.length === 0;
+            const page = {
+                results: result.results,
+                ...(result.meta ? { meta: result.meta } : {}),
+                page: pageNumber,
+                offset,
+                loaded,
+                complete,
+                ...(returnedCursor ? { cursor: returnedCursor } : {}),
+                ...(!cursorMode && snapshot ? { snapshot } : {})
+            };
+            options.onProgress?.(page);
+            yield connectSuccess(page, queried.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/dist/request-coordinator.d.ts

@@ -0,0 +1,29 @@
+import { type CollectionOperation } from "@mdbase-dev/connect-protocol";
+import type { ConnectRequestOptions, MdbaseCollectionTransport } from "./operation-types.js";
+interface CoordinatorLimits {
+    foregroundCapacity?: number;
+    foregroundQueueCapacity?: number;
+    mutationQueueCapacity?: number;
+}
+/** One bounded request owner for a selected connection. */
+export declare class CollectionRequestCoordinator implements MdbaseCollectionTransport {
+    private readonly transport;
+    private readonly requestTimeoutMs;
+    private readonly foregroundCapacity;
+    private readonly foregroundQueueCapacity;
+    private readonly mutationQueueCapacity;
+    private readonly foregroundQueue;
+    private readonly mutationQueue;
+    private readonly identicalReads;
+    private readonly latestFamilies;
+    private activeForeground;
+    private mutationActive;
+    constructor(transport: MdbaseCollectionTransport, requestTimeoutMs: number | null, limits?: CoordinatorLimits);
+    operation<Result>(operation: CollectionOperation, input: unknown, options?: ConnectRequestOptions): Promise<Result>;
+    private schedule;
+    private replaceLatest;
+    private releaseLatest;
+    private pump;
+    private start;
+}
+export {};

package/dist/request-coordinator.js

@@ -0,0 +1,212 @@
+import { isMutatingOperation } from "@mdbase-dev/connect-protocol";
+import { connectError } from "./errors.js";
+import { requestAbortReason, requestOptionsWithinBudget, withCooperativeRequestBudget } from "./request-budget.js";
+const DEFAULT_FOREGROUND_CAPACITY = 4;
+const DEFAULT_QUEUE_CAPACITY = 32;
+/** One bounded request owner for a selected connection. */
+export class CollectionRequestCoordinator {
+    transport;
+    requestTimeoutMs;
+    foregroundCapacity;
+    foregroundQueueCapacity;
+    mutationQueueCapacity;
+    foregroundQueue = [];
+    mutationQueue = [];
+    identicalReads = new Map();
+    latestFamilies = new Map();
+    activeForeground = 0;
+    mutationActive = false;
+    constructor(transport, requestTimeoutMs, limits = {}) {
+        this.transport = transport;
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.foregroundCapacity = positiveCapacity(limits.foregroundCapacity, DEFAULT_FOREGROUND_CAPACITY);
+        this.foregroundQueueCapacity = positiveCapacity(limits.foregroundQueueCapacity, DEFAULT_QUEUE_CAPACITY);
+        this.mutationQueueCapacity = positiveCapacity(limits.mutationQueueCapacity, DEFAULT_QUEUE_CAPACITY);
+    }
+    operation(operation, input, options = {}) {
+        const read = !isMutatingOperation(operation, input);
+        const coordination = validatedCoordination(options.coordination, read);
+        const coalesceKey = read
+            && coordination.coalesce !== false
+            && !coordination.latestWins
+            && options.signal === undefined
+            ? stableRequestKey(operation, input, options.timeoutMs)
+            : undefined;
+        if (coalesceKey) {
+            const existing = this.identicalReads.get(coalesceKey);
+            if (existing)
+                return existing;
+        }
+        const request = withCooperativeRequestBudget(options, this.requestTimeoutMs, (budget) => this.schedule(operation, input, options, coordination, read, budget));
+        if (coalesceKey) {
+            this.identicalReads.set(coalesceKey, request);
+            void request.finally(() => {
+                if (this.identicalReads.get(coalesceKey) === request) {
+                    this.identicalReads.delete(coalesceKey);
+                }
+            }).catch(() => undefined);
+        }
+        return request;
+    }
+    schedule(operation, input, options, coordination, read, budget) {
+        const replacement = coordination.latestWins
+            ? this.replaceLatest(coordination.family)
+            : undefined;
+        const combined = combineSignals(budget.signal, replacement?.signal);
+        const { coordination: _coordination, ...transportOptions } = options;
+        const withinBudget = requestOptionsWithinBudget({ ...transportOptions, timeoutMs: null }, budget);
+        const run = () => this.transport.operation(operation, input, {
+            ...withinBudget,
+            signal: combined.signal
+        });
+        const queue = read ? this.foregroundQueue : this.mutationQueue;
+        const capacity = read ? this.foregroundQueueCapacity : this.mutationQueueCapacity;
+        if (queue.length >= capacity) {
+            combined.dispose();
+            this.releaseLatest(coordination.family, replacement);
+            return Promise.reject(connectError("connector_busy", "The selected connection request queue is full.", { operationOutcome: "not_sent", status: 503 }));
+        }
+        return new Promise((resolve, reject) => {
+            const queued = {
+                budget,
+                run,
+                resolve: (result) => resolve(result),
+                reject,
+                started: false,
+                settled: false
+            };
+            const abortQueued = () => {
+                if (queued.started || queued.settled)
+                    return;
+                queued.settled = true;
+                queued.reject(requestAbortReason(combined.signal));
+                combined.dispose();
+                this.releaseLatest(coordination.family, replacement);
+            };
+            combined.signal.addEventListener("abort", abortQueued, { once: true });
+            const originalRun = queued.run;
+            queued.run = async () => {
+                combined.signal.removeEventListener("abort", abortQueued);
+                try {
+                    if (combined.signal.aborted)
+                        throw requestAbortReason(combined.signal);
+                    return await originalRun();
+                }
+                finally {
+                    combined.dispose();
+                    this.releaseLatest(coordination.family, replacement);
+                }
+            };
+            queue.push(queued);
+            this.pump();
+        });
+    }
+    replaceLatest(family) {
+        const replacement = new AbortController();
+        this.latestFamilies.get(family)?.abort(connectError("operation_cancelled", "A newer request replaced this read before it changed the collection.", { operationOutcome: "not_sent" }));
+        this.latestFamilies.set(family, replacement);
+        return replacement;
+    }
+    releaseLatest(family, controller) {
+        if (family && controller && this.latestFamilies.get(family) === controller) {
+            this.latestFamilies.delete(family);
+        }
+    }
+    pump() {
+        while (this.activeForeground < this.foregroundCapacity) {
+            const request = nextLive(this.foregroundQueue);
+            if (!request)
+                break;
+            this.activeForeground += 1;
+            this.start(request, () => {
+                this.activeForeground -= 1;
+                this.pump();
+            });
+        }
+        if (!this.mutationActive) {
+            const request = nextLive(this.mutationQueue);
+            if (request) {
+                this.mutationActive = true;
+                this.start(request, () => {
+                    this.mutationActive = false;
+                    this.pump();
+                });
+            }
+        }
+    }
+    start(request, release) {
+        request.started = true;
+        void request.run().then((result) => {
+            if (!request.settled) {
+                request.settled = true;
+                request.resolve(result);
+            }
+        }, (error) => {
+            if (!request.settled) {
+                request.settled = true;
+                request.reject(error);
+            }
+        }).finally(release);
+    }
+}
+function nextLive(queue) {
+    while (queue.length > 0) {
+        const request = queue.shift();
+        if (!request.settled)
+            return request;
+    }
+    return undefined;
+}
+function validatedCoordination(coordination, read) {
+    const resolved = coordination ?? {};
+    if (resolved.latestWins && !read) {
+        throw new TypeError("latestWins coordination is available only for read operations.");
+    }
+    if (resolved.latestWins && !resolved.family?.trim()) {
+        throw new TypeError("latestWins coordination requires a non-empty family.");
+    }
+    return resolved;
+}
+function stableRequestKey(operation, input, timeoutMs) {
+    return `${operation}:${timeoutMs === undefined ? "default" : String(timeoutMs)}:${stableJson(input)}`;
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => `${JSON.stringify(key)}:${stableJson(nested)}`)
+        .join(",")}}`;
+}
+function combineSignals(primary, secondary) {
+    if (!secondary)
+        return { signal: primary, dispose: () => undefined };
+    const controller = new AbortController();
+    const abortPrimary = () => controller.abort(primary.reason);
+    const abortSecondary = () => controller.abort(secondary.reason);
+    if (primary.aborted)
+        abortPrimary();
+    else
+        primary.addEventListener("abort", abortPrimary, { once: true });
+    if (secondary.aborted)
+        abortSecondary();
+    else
+        secondary.addEventListener("abort", abortSecondary, { once: true });
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            primary.removeEventListener("abort", abortPrimary);
+            secondary.removeEventListener("abort", abortSecondary);
+        }
+    };
+}
+function positiveCapacity(value, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new TypeError("Request coordinator capacities must be positive safe integers.");
+    }
+    return resolved;
+}

package/package.json

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