@mdbase-dev/connect 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/collection-client.d.ts

@@ -1,4 +1,5 @@
-import type { CollectionChange, CollectionChangesPage, CollectionDescription, CollectionOperation, CollectionTypeDocument, CreateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, JsonObject, MdbaseOperationEnvelope, ReadViewSourceInput, RecordDocument, SavedViewExecution, SavedViewList, SavedViewSourceDocument, TypePackInstallResult, TypePackProvision, UpdateViewSourceInput } from "@mdbase-dev/connect-protocol";
+import type { CollectionChange, CollectionChangesPage, CollectionDescription, CollectionOperation, CollectionTypeDocument, CreateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, JsonObject, ReadViewSourceInput, RecordDocument, SavedViewExecution, SavedViewList, SavedViewSourceDocument, TypePackInstallResult, TypePackProvision, UpdateViewSourceInput } 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, CreateInput, CreateTypeInput, DeleteInput, DeletePreflightResult, DeleteResult, MdbaseCollectionTransport, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, OperationRequestOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, RenameInput, RenamePreflightResult, RenameResult, UpdateInput, UpdateTypeInput, WatchOptions } from "./operation-types.js";
 /**
  * Typed collection operations independent of OAuth, HTTP, or storage.
@@ -9,49 +10,51 @@ import type { ChangesInput, CreateInput, CreateTypeInput, DeleteInput, DeletePre
 export declare class MdbaseCollectionClient<Frontmatter extends JsonObject = JsonObject> {
     private readonly transport;
     constructor(transport: MdbaseCollectionTransport);
-    operation<Result>(operation: CollectionOperation, input: unknown, options?: OperationRequestOptions): Promise<Result>;
-    describe(): Promise<CollectionDescription>;
-    changes(input?: ChangesInput, options?: OperationRequestOptions): Promise<CollectionChangesPage>;
-    read(input: ReadInput): Promise<MdbaseOperationEnvelope<RecordDocument<Frontmatter>>>;
-    query(input?: QueryInput, options?: OperationRequestOptions): Promise<MdbaseOperationEnvelope<QueryResult<Frontmatter>>>;
-    queryPages(input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): AsyncGenerator<QueryPage<Frontmatter>>;
-    queryAll(input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): Promise<QueryResult<Frontmatter>>;
-    listViews(): Promise<MdbaseOperationEnvelope<SavedViewList>>;
-    executeView(input: ExecuteViewInput): Promise<MdbaseOperationEnvelope<SavedViewExecution<Frontmatter>>>;
-    readViewSource(input: ReadViewSourceInput): Promise<MdbaseOperationEnvelope<SavedViewSourceDocument>>;
-    createViewSource(input: CreateViewSourceInput): Promise<MdbaseOperationEnvelope<SavedViewSourceDocument>>;
-    updateViewSource(input: UpdateViewSourceInput): Promise<MdbaseOperationEnvelope<SavedViewSourceDocument>>;
-    deleteViewSource(input: DeleteViewSourceInput): Promise<MdbaseOperationEnvelope<DeleteViewSourceResult>>;
-    create(input: CreateInput<Frontmatter>): Promise<MdbaseOperationEnvelope<RecordDocument<Frontmatter>>>;
-    update(input: UpdateInput<Frontmatter>): Promise<MdbaseOperationEnvelope<RecordDocument<Frontmatter>>>;
-    delete(input: DeleteInput, options?: OperationRequestOptions): Promise<MdbaseOperationEnvelope<DeleteResult>>;
-    preflightDelete(input: DeleteInput, options?: OperationRequestOptions): Promise<MdbaseOperationEnvelope<DeletePreflightResult>>;
-    rename(input: RenameInput, options?: OperationRequestOptions): Promise<MdbaseOperationEnvelope<RenameResult>>;
-    preflightRename(input: RenameInput, options?: OperationRequestOptions): Promise<MdbaseOperationEnvelope<RenamePreflightResult>>;
-    validate(input?: JsonObject): Promise<MdbaseOperationEnvelope>;
-    readType(input: ReadTypeInput): Promise<MdbaseOperationEnvelope<CollectionTypeDocument>>;
-    createType(input: CreateTypeInput): Promise<MdbaseOperationEnvelope<CollectionTypeDocument>>;
-    updateType(input: UpdateTypeInput): Promise<MdbaseOperationEnvelope<CollectionTypeDocument>>;
-    installTypePack(input: TypePackProvision): Promise<MdbaseOperationEnvelope<TypePackInstallResult>>;
-    listTimers(namespace: string): Promise<MdbaseTimerList>;
+    operation<Result>(operation: CollectionOperation, input: unknown, options?: OperationRequestOptions): Promise<ConnectOutcome<Result>>;
+    describe(): Promise<ConnectOutcome<CollectionDescription, CollectionDescriptionProblemCode>>;
+    changes(input?: ChangesInput, options?: OperationRequestOptions): Promise<ConnectOutcome<CollectionChangesPage, CollectionChangesProblemCode>>;
+    read(input: ReadInput): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionReadProblemCode>>;
+    query(input?: QueryInput, options?: OperationRequestOptions): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
+    queryPages(input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<QueryPage<Frontmatter>, CollectionQueryProblemCode>>;
+    queryAll(input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
+    listViews(): Promise<ConnectOutcome<SavedViewList, CollectionReadProblemCode>>;
+    executeView(input: ExecuteViewInput): Promise<ConnectOutcome<SavedViewExecution<Frontmatter>, CollectionReadProblemCode>>;
+    readViewSource(input: ReadViewSourceInput): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionReadProblemCode>>;
+    createViewSource(input: CreateViewSourceInput): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionMutationProblemCode>>;
+    updateViewSource(input: UpdateViewSourceInput): Promise<ConnectOutcome<SavedViewSourceDocument, CollectionMutationProblemCode>>;
+    deleteViewSource(input: DeleteViewSourceInput): Promise<ConnectOutcome<DeleteViewSourceResult, CollectionMutationProblemCode>>;
+    create(input: CreateInput<Frontmatter>): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionMutationProblemCode>>;
+    update(input: UpdateInput<Frontmatter>): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionMutationProblemCode>>;
+    delete(input: DeleteInput, options?: OperationRequestOptions): Promise<ConnectOutcome<DeleteResult, CollectionMutationProblemCode>>;
+    preflightDelete(input: DeleteInput, options?: OperationRequestOptions): Promise<ConnectOutcome<DeletePreflightResult, CollectionMutationProblemCode>>;
+    rename(input: RenameInput, options?: OperationRequestOptions): Promise<ConnectOutcome<RenameResult, CollectionMutationProblemCode>>;
+    preflightRename(input: RenameInput, options?: OperationRequestOptions): Promise<ConnectOutcome<RenamePreflightResult, CollectionMutationProblemCode>>;
+    validate(input?: JsonObject): Promise<ConnectOutcome<JsonObject, CollectionReadProblemCode>>;
+    readType(input: ReadTypeInput): Promise<ConnectOutcome<CollectionTypeDocument, CollectionTypeProblemCode>>;
+    createType(input: CreateTypeInput): Promise<ConnectOutcome<CollectionTypeDocument, CollectionTypeProblemCode>>;
+    updateType(input: UpdateTypeInput): Promise<ConnectOutcome<CollectionTypeDocument, CollectionTypeProblemCode>>;
+    installTypePack(input: TypePackProvision): Promise<ConnectOutcome<TypePackInstallResult, CollectionTypeProblemCode>>;
+    listTimers(namespace: string): Promise<ConnectOutcome<MdbaseTimerList, CollectionReadProblemCode>>;
     putTimer(input: {
         namespace: string;
         criterion_id: string;
         timer: MdbaseDesiredTimer;
-    }): Promise<MdbaseTimer>;
+    }): Promise<ConnectOutcome<MdbaseTimer, CollectionMutationProblemCode>>;
     cancelTimer(input: {
         namespace: string;
         id: string;
         generation?: number;
-    }): Promise<{
+    }): Promise<ConnectOutcome<{
         namespace: string;
         id: string;
         cancelled: boolean;
-    }>;
+    }, CollectionMutationProblemCode>>;
     reconcileTimers(input: {
         namespace: string;
         criterion_id: string;
         timers: MdbaseDesiredTimer[];
-    }): Promise<MdbaseTimerReconciliation>;
-    watch(options?: WatchOptions): AsyncGenerator<CollectionChange>;
+    }): Promise<ConnectOutcome<MdbaseTimerReconciliation, CollectionMutationProblemCode>>;
+    watch(options?: WatchOptions): AsyncGenerator<ConnectOutcome<CollectionChange, CollectionChangesProblemCode>>;
+    private rawOperation;
+    private envelopeOperation;
 }

package/dist/collection-client.js

@@ -1,5 +1,6 @@
 import { abortableDelay } from "./async.js";
-import { MdbaseConnectError, isRetryableConnectError, unwrapOperation } from "./errors.js";
+import { 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";
 /**
  * Typed collection operations independent of OAuth, HTTP, or storage.
  *
@@ -12,19 +13,19 @@ export class MdbaseCollectionClient {
         this.transport = transport;
     }
     operation(operation, input, options) {
-        return this.transport.operation(operation, input, options);
+        return captureConnectOutcome(() => this.transport.operation(operation, input, options), ALL_CONNECT_PROBLEM_CODES);
     }
     describe() {
-        return this.operation("describe", {});
+        return this.rawOperation("describe", {}, COLLECTION_DESCRIPTION_PROBLEM_CODES);
     }
     changes(input = {}, options) {
-        return this.operation("changes", input, options);
+        return this.rawOperation("changes", input, COLLECTION_CHANGES_PROBLEM_CODES, options);
     }
     read(input) {
-        return this.operation("read", input);
+        return this.envelopeOperation("read", input, COLLECTION_READ_PROBLEM_CODES);
     }
     query(input = {}, options) {
-        return this.operation("query", input, options);
+        return this.envelopeOperation("query", input, COLLECTION_QUERY_PROBLEM_CODES, options);
     }
     async *queryPages(input = {}, options = {}) {
         const { offset: requestedOffset, limit: requestedLimit, snapshot: requestedSnapshot, ...criteria } = input;
@@ -35,15 +36,21 @@ export class MdbaseCollectionClient {
         let loaded = 0;
         let pageNumber = 0;
         while (!options.signal?.aborted) {
-            const result = unwrapOperation(await this.query({
+            const queried = await this.query({
                 ...criteria,
                 offset,
                 limit: pageNumber === 0 ? firstPageSize : pageSize,
                 ...(snapshot ? { snapshot } : {})
-            }, { signal: options.signal }));
+            }, { signal: options.signal });
+            if (!queried.ok) {
+                yield queried;
+                return;
+            }
+            const result = queried.value;
             const returnedSnapshot = result.meta?.snapshot;
             if (snapshot && returnedSnapshot && snapshot !== returnedSnapshot) {
-                throw new MdbaseConnectError("query_snapshot_changed", "The collection query snapshot changed while paging. Refresh the query before continuing.", { recovery: "refresh" });
+                yield connectFailure(connectProblem("query_snapshot_changed", "The collection query snapshot changed while paging. Refresh the query before continuing."));
+                return;
             }
             if (!snapshot && returnedSnapshot)
                 snapshot = returnedSnapshot;
@@ -59,7 +66,7 @@ export class MdbaseCollectionClient {
                 ...(snapshot ? { snapshot } : {})
             };
             options.onProgress?.(page);
-            yield page;
+            yield connectSuccess(page, queried.diagnostics);
             if (complete)
                 return;
             offset += result.results.length;
@@ -69,11 +76,16 @@ export class MdbaseCollectionClient {
     async queryAll(input = {}, options = {}) {
         const results = [];
         let finalPage;
-        for await (const page of this.queryPages(input, options)) {
+        const diagnostics = [];
+        for await (const outcome of this.queryPages(input, options)) {
+            if (!outcome.ok)
+                return outcome;
+            const page = outcome.value;
             results.push(...page.results);
             finalPage = page;
+            diagnostics.push(...outcome.diagnostics);
         }
-        return {
+        return connectSuccess({
             results,
             meta: {
                 ...(finalPage?.meta ?? {}),
@@ -81,70 +93,70 @@ export class MdbaseCollectionClient {
                 has_more: finalPage ? !finalPage.complete : false,
                 ...(finalPage?.snapshot ? { snapshot: finalPage.snapshot } : {})
             }
-        };
+        }, diagnostics);
     }
     listViews() {
-        return this.operation("list_views", {});
+        return this.envelopeOperation("list_views", {}, COLLECTION_READ_PROBLEM_CODES);
     }
     executeView(input) {
-        return this.operation("execute_view", input);
+        return this.envelopeOperation("execute_view", input, COLLECTION_READ_PROBLEM_CODES);
     }
     readViewSource(input) {
-        return this.operation("read_view_source", input);
+        return this.envelopeOperation("read_view_source", input, COLLECTION_READ_PROBLEM_CODES);
     }
     createViewSource(input) {
-        return this.operation("create_view_source", input);
+        return this.envelopeOperation("create_view_source", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     updateViewSource(input) {
-        return this.operation("update_view_source", input);
+        return this.envelopeOperation("update_view_source", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     deleteViewSource(input) {
-        return this.operation("delete_view_source", input);
+        return this.envelopeOperation("delete_view_source", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     create(input) {
-        return this.operation("create", input);
+        return this.envelopeOperation("create", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     update(input) {
-        return this.operation("update", input);
+        return this.envelopeOperation("update", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     delete(input, options) {
-        return this.operation("delete", input, options);
+        return this.envelopeOperation("delete", input, COLLECTION_MUTATION_PROBLEM_CODES, options);
     }
     preflightDelete(input, options) {
-        return this.operation("delete", { ...input, check_backlinks: true, dry_run: true }, options);
+        return this.envelopeOperation("delete", { ...input, check_backlinks: true, dry_run: true }, COLLECTION_MUTATION_PROBLEM_CODES, options);
     }
     rename(input, options) {
-        return this.operation("rename", input, options);
+        return this.envelopeOperation("rename", input, COLLECTION_MUTATION_PROBLEM_CODES, options);
     }
     preflightRename(input, options) {
-        return this.operation("rename", { ...input, dry_run: true }, options);
+        return this.envelopeOperation("rename", { ...input, dry_run: true }, COLLECTION_MUTATION_PROBLEM_CODES, options);
     }
     validate(input = {}) {
-        return this.operation("validate", input);
+        return this.envelopeOperation("validate", input, COLLECTION_READ_PROBLEM_CODES);
     }
     readType(input) {
-        return this.operation("read_type", input);
+        return this.envelopeOperation("read_type", input, COLLECTION_TYPE_PROBLEM_CODES);
     }
     createType(input) {
-        return this.operation("create_type", input);
+        return this.envelopeOperation("create_type", input, COLLECTION_TYPE_PROBLEM_CODES);
     }
     updateType(input) {
-        return this.operation("update_type", input);
+        return this.envelopeOperation("update_type", input, COLLECTION_TYPE_PROBLEM_CODES);
     }
     installTypePack(input) {
-        return this.operation("install_type_pack", input);
+        return this.envelopeOperation("install_type_pack", input, COLLECTION_TYPE_PROBLEM_CODES);
     }
     listTimers(namespace) {
-        return this.operation("list_timers", { namespace });
+        return this.rawOperation("list_timers", { namespace }, COLLECTION_READ_PROBLEM_CODES);
     }
     putTimer(input) {
-        return this.operation("put_timer", input);
+        return this.rawOperation("put_timer", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     cancelTimer(input) {
-        return this.operation("cancel_timer", input);
+        return this.rawOperation("cancel_timer", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     reconcileTimers(input) {
-        return this.operation("reconcile_timers", input);
+        return this.rawOperation("reconcile_timers", input, COLLECTION_MUTATION_PROBLEM_CODES);
     }
     async *watch(options = {}) {
         let cursor = options.cursor;
@@ -154,47 +166,81 @@ export class MdbaseCollectionClient {
         let connected = false;
         options.onStatus?.({ state: "connecting", ...(cursor === undefined ? {} : { cursor }) });
         while (!options.signal?.aborted) {
-            try {
-                if (cursor === undefined)
-                    cursor = (await this.changes({}, { signal: options.signal })).cursor;
-                const page = await this.changes({ after: cursor, limit: 200 }, { signal: options.signal });
-                if (page.reset) {
-                    const error = new MdbaseConnectError("change_cursor_reset", "The collection change cursor expired. Refresh collection state before subscribing again.");
-                    options.onStatus?.({ state: "reset_required", cursor, error });
-                    throw error;
-                }
-                const recovered = failures > 0;
-                failures = 0;
-                if (!connected || recovered)
-                    options.onStatus?.({ state: "connected", cursor, recovered });
-                connected = true;
-                for (const event of page.events)
-                    yield event;
-                cursor = page.cursor;
-                if (!page.has_more)
-                    await abortableDelay(pollInterval, options.signal);
-            }
-            catch (error) {
+            const changed = await this.changes(cursor === undefined ? {} : { after: cursor, limit: 200 }, { signal: options.signal });
+            if (!changed.ok) {
+                const problem = changed.problem;
                 if (options.signal?.aborted)
                     return;
-                if (!retry || !isRetryableConnectError(error))
-                    throw error;
+                if (!retry || problem.recovery !== "retry") {
+                    yield changed;
+                    return;
+                }
                 connected = false;
                 failures += 1;
-                if (retry.maxAttempts !== undefined && failures > retry.maxAttempts)
-                    throw error;
+                if (retry.maxAttempts !== undefined && failures > retry.maxAttempts) {
+                    yield changed;
+                    return;
+                }
                 const retryInMs = Math.min(retry.maxDelayMs, Math.round(retry.initialDelayMs * retry.multiplier ** (failures - 1)));
                 options.onStatus?.({
                     state: "reconnecting",
                     ...(cursor === undefined ? {} : { cursor }),
                     attempt: failures,
                     retryInMs,
-                    error
+                    problem
                 });
-                await abortableDelay(retryInMs, options.signal);
+                try {
+                    await abortableDelay(retryInMs, options.signal);
+                }
+                catch {
+                    if (!options.signal?.aborted)
+                        throw connectError("operation_failed", "Watch retry delay failed unexpectedly.");
+                }
+                continue;
+            }
+            const page = changed.value;
+            if (cursor === undefined) {
+                cursor = page.cursor;
+                continue;
+            }
+            if (page.reset) {
+                const problem = connectProblem("change_cursor_reset", "The collection change cursor expired. Refresh collection state before subscribing again.");
+                options.onStatus?.({ state: "reset_required", cursor, problem });
+                yield connectFailure(problem);
+                return;
+            }
+            const recovered = failures > 0;
+            failures = 0;
+            if (!connected || recovered)
+                options.onStatus?.({ state: "connected", cursor, recovered });
+            connected = true;
+            for (const event of page.events)
+                yield connectSuccess(event);
+            cursor = page.cursor;
+            if (!page.has_more) {
+                try {
+                    await abortableDelay(pollInterval, options.signal);
+                }
+                catch {
+                    if (!options.signal?.aborted)
+                        throw connectError("operation_failed", "Watch polling delay failed unexpectedly.");
+                }
             }
         }
     }
+    rawOperation(operation, input, allowedCodes, options) {
+        return captureConnectOutcome(() => this.transport.operation(operation, input, options), allowedCodes);
+    }
+    async envelopeOperation(operation, input, allowedCodes, options) {
+        const transported = await captureConnectOutcome(() => this.transport.operation(operation, input, options), allowedCodes);
+        if (!transported.ok)
+            return transported;
+        const envelope = transported.value;
+        if (!envelope.valid) {
+            return connectFailure(operationProblem(envelope));
+        }
+        return connectSuccess(envelope.result, envelope.diagnostics);
+    }
 }
 function watchRetryPolicy(options) {
     if (options === false)

package/dist/connect.d.ts

@@ -3,6 +3,7 @@ import { MdbaseConnection, type MdbaseAuthorizationOutcome, type MdbaseAuthoriza
 import type { MdbaseConnectionInfo } from "./connection-types.js";
 import { type GrantKeyStore } from "./crypto.js";
 import { type Application } from "./internal-types.js";
+import { type AuthorizationProblemCode, type ConnectOutcome, type RegistrationProblemCode } from "./outcomes.js";
 import { MdbaseSession, type MdbaseSessionOptions, type MdbaseUnavailableReason } from "./session.js";
 export interface MdbaseConnectOptions {
     serverUrl: string;
@@ -26,11 +27,11 @@ export interface MdbaseConnectOptions {
 export declare class MdbaseConnect<Frontmatter extends JsonObject = JsonObject> {
     private readonly internals;
     constructor(options: MdbaseConnectOptions);
-    register(): Promise<Application>;
-    authorize(options?: MdbaseAuthorizeOptions): Promise<MdbaseAuthorizationOutcome<Frontmatter>>;
+    register(): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
+    authorize(options?: MdbaseAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
     createSession(options: MdbaseSessionOptions): MdbaseSession<Frontmatter>;
     environment(): MdbaseConnectEnvironment;
-    completeAuthorization(callbackUrl?: string): Promise<MdbaseAuthorizationResult<Frontmatter>>;
+    completeAuthorization(callbackUrl?: string): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
     connections(): MdbaseConnectionInfo[];
     connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
     unavailableReason(collectionId: string): MdbaseUnavailableReason | null;