@archont561/qgis-sdk 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,106 +1,67 @@
-/**
-* Public 0.1.0 contract, wire-limit, and error primitives for the QGIS SDK bridge.
-*
-* Mirrors the QGIS-free `qgis_sdk.models` and `qgis_sdk.declarations`
-* (`schema_version = 1`) contracts without importing browser or Qt globals.
-*/
-declare const MAX_SAFE_INTEGER: number;
-declare const MIN_SAFE_INTEGER: number;
-declare const PLUGIN_DESCRIPTION_SCHEMA_VERSION: 1;
-type ValidationDirection = "request" | "result";
-interface SerializedValidationIssue {
-	readonly path: (string | number)[];
-	readonly code: string;
+import { MAX_SAFE_INTEGER2, MIN_SAFE_INTEGER2, PLUGIN_DESCRIPTION_SCHEMA_VERSION2, ValidationDirection2, SerializedValidationIssue2, SerializedContractValidationError2, ActionDescription2, StreamEventKind2, StreamDescription2, PluginDescription2, isSafeJsonInteger2, QgisSdkDeclarationError2, QgisSdkValidationIssue2, QgisSdkContractValidationError2, parsePluginDescription2, BRIDGE_PROTOCOL_VERSION2, MAX_CALL_ID_LENGTH2, BridgeFailure2, InvokeReply2, StreamTerminalKind2, BridgeStreamEvent2, BridgeStreamTerminal2, BridgeEventFrame2, BridgeTerminalFrame2, BridgeStreamFrame2, WireTransport2, BridgeClientOptions2, InvokeOptions2, QgisSdkBridgeProtocolError2, QgisSdkBridgeTimeoutError2, QgisSdkBridgeAbortedError2, QgisSdkBridgeClosedError2, QgisSdkBridgeSequenceError2, QgisSdkBridgeStreamEndedError2, QgisSdkBridgeRemoteError2, parseInvokeReply2, parseStreamFrame2, SubscriptionHandlers2, BridgeSubscription2, BridgeClient2 } from "./shared/chunk-wtv4vt4q.js";
+import "./shared/chunk-khemhx86.js";
+import { OperationShape2, StreamShape2, OperationMap2, StreamMap2, BridgeSchema2, OperationsOf2, StreamsOf2, defineBridgeSchema2 } from "./shared/chunk-jjx14tgd.js";
+import { QgisSdkOptions2, StreamHandlers2, StreamHandle2, OperationMethod2, StreamMethod2, QgisSdkHost2, QgisSdkCore2, OperationTree2, StreamTree2, QGIS_SDK_MEMBERS2, QgisSdk2 } from "./shared/chunk-tmca1ynt.js";
+import { QgisSdkError2 } from "./shared/chunk-pdj2fxjb.js";
+/** One schema of the declared dialect, as the description carries it. */
+type DeclaredSchema = Readonly<Record<string, unknown>>;
+/** Options for {@link validateAgainstSchema}. */
+interface ValidateOptions {
+	/** Ignore properties the schema does not name (results and events). */
+	readonly allowUnknown?: boolean;
+	/** Where the value sits, prefixed to every issue's path. */
+	readonly path?: readonly (string | number)[];
 }
-interface SerializedContractValidationError {
-	readonly code: string;
-	readonly direction: ValidationDirection;
-	readonly issues: SerializedValidationIssue[];
-}
-interface ActionDescription {
-	readonly id: string;
-	readonly title: string;
-	readonly handler: string;
-	readonly request: Readonly<Record<string, unknown>>;
-	readonly result: Readonly<Record<string, unknown>>;
-}
-/** The event kinds a stream may declare; the frame carries the same three. */
-type StreamEventKind = "data" | "progress" | "state";
-/**
-* A declared stream (decision-28): a request in, one payload schema per
-* declared event kind out. There is no `result`: the reply to a subscription is
-* the protocol's acknowledgement, not something an author declares.
-*/
-interface StreamDescription {
-	readonly id: string;
-	readonly title: string;
-	readonly handler: string;
-	readonly request: Readonly<Record<string, unknown>>;
-	readonly events: Readonly<Partial<Record<StreamEventKind, Readonly<Record<string, unknown>>>>>;
-}
-interface PluginDescription {
-	readonly schema_version: 1;
-	readonly id: string;
-	readonly title: string;
-	readonly actions: readonly ActionDescription[];
-	/** Declared streams; a description from a host that predates them is empty. */
-	readonly streams: readonly StreamDescription[];
-}
-/**
-* Return whether `value` is a finite integer within the JavaScript-safe wire range.
-*/
-declare function isSafeJsonInteger(value: unknown): value is number;
-/**
-* Base class for expected SDK errors across the bridge boundary.
-*/
-declare class QgisSdkError extends Error {
+/** Which side of a call a contract issue belongs to. */
+type ContractDirection = "request" | "result" | "event";
+/** The JSON form of {@link QgisSdkContractError}. */
+interface SerializedContractError {
 	readonly code: string;
-	constructor(message: string, code?: string);
+	readonly operation: string;
+	readonly direction: ContractDirection;
+	readonly issues: SerializedValidationIssue2[];
 }
 /**
-* An operation attempted to use an already disposed owner scope.
-*/
-declare class QgisSdkScopeClosedError extends QgisSdkError {
-	constructor();
-}
-/**
-* The selected runtime does not offer an explicitly requested capability.
+* An argument, a reply or an event does not match the declared contract.
+*
+* The code is the one both languages use for this category, so a page that
+* already matches `contract_validation_failed` needs no second branch.
 */
-declare class QgisSdkUnsupportedCapabilityError extends QgisSdkError {
-	readonly capability: string;
-	constructor(capability: string);
+declare class QgisSdkContractError extends QgisSdkError2 {
+	readonly operation: string;
+	readonly direction: ContractDirection;
+	readonly issues: readonly QgisSdkValidationIssue2[];
+	constructor(operation: string, direction: ContractDirection, issues: readonly QgisSdkValidationIssue2[]);
+	toJSON(): SerializedContractError;
 }
 /**
-* A declaration cannot be represented or parsed in the versioned contract.
+* Return every issue `value` has against `schema`; an empty array is a match.
+*
+* Throws {@link QgisSdkDeclarationError} when `schema` leaves the declared
+* dialect, because that is a fault in the declaration, never in the value.
 */
-declare class QgisSdkDeclarationError extends QgisSdkError {
+declare function validateAgainstSchema(value: unknown, schema: DeclaredSchema, options?: ValidateOptions): QgisSdkValidationIssue2[];
+/** The web view did not provide a usable channel. */
+declare class QgisSdkWebChannelError extends QgisSdkError2 {
 	constructor(message: string);
 }
-/**
-* Safe, structured location and category for a rejected contract value.
-*/
-declare class QgisSdkValidationIssue {
-	readonly path: readonly (string | number)[];
-	readonly code: string;
-	constructor(path: readonly (string | number)[], code: string);
-	toJSON(): SerializedValidationIssue;
-}
-/**
-* A request or result did not satisfy its declared wire contract.
-*/
-declare class QgisSdkContractValidationError extends QgisSdkError {
-	readonly direction: ValidationDirection;
-	readonly issues: readonly QgisSdkValidationIssue[];
-	constructor(direction: ValidationDirection, issues: readonly QgisSdkValidationIssue[]);
-	toJSON(): SerializedContractValidationError;
+/** The transport {@link createWebChannelTransport} returns. */
+interface WebChannelTransport extends WireTransport2 {
+	/** Resolves once the channel object answered; rejects when it never will. */
+	readonly ready: Promise<void>;
+	/** Stop forwarding messages; sends after this throw. */
+	close(): void;
 }
+/** True inside a QGIS web view, where Qt injected its transport and script. */
+declare function insideQgis(): boolean;
 /**
-* Return whether `value` is a non-null, non-array object: the shape every wire
-* envelope, description and event payload must have before its fields are read.
-*/
-declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
-/**
-* Parse and validate a version 1 `PluginDescription` emitted by `describe_plugin`.
+* Connect to the channel object `objectName` and return a transport on it.
+*
+* Throws {@link QgisSdkWebChannelError} synchronously outside a QGIS web view,
+* so a page learns in its first statement that it has no host to talk to.
+* Inside one, messages sent before the channel is ready are queued and
+* delivered in order once it is; `ready` rejects (and queued sends are
+* dropped) when the host registered no object under that name.
 */
-declare function parsePluginDescription(input: string | Readonly<Record<string, unknown>>): PluginDescription;
-export { ActionDescription, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, PLUGIN_DESCRIPTION_SCHEMA_VERSION, PluginDescription, QgisSdkContractValidationError, QgisSdkDeclarationError, QgisSdkError, QgisSdkScopeClosedError, QgisSdkUnsupportedCapabilityError, QgisSdkValidationIssue, SerializedContractValidationError, SerializedValidationIssue, StreamDescription, StreamEventKind, ValidationDirection, isPlainRecord, isSafeJsonInteger, parsePluginDescription };
+declare function createWebChannelTransport(objectName?: string): WebChannelTransport;
+export { ActionDescription2 as ActionDescription, BRIDGE_PROTOCOL_VERSION2 as BRIDGE_PROTOCOL_VERSION, BridgeClient2 as BridgeClient, BridgeClientOptions2 as BridgeClientOptions, BridgeEventFrame2 as BridgeEventFrame, BridgeFailure2 as BridgeFailure, BridgeSchema2 as BridgeSchema, BridgeStreamEvent2 as BridgeStreamEvent, BridgeStreamFrame2 as BridgeStreamFrame, BridgeStreamTerminal2 as BridgeStreamTerminal, BridgeSubscription2 as BridgeSubscription, BridgeTerminalFrame2 as BridgeTerminalFrame, ContractDirection, DeclaredSchema, InvokeOptions2 as InvokeOptions, InvokeReply2 as InvokeReply, MAX_CALL_ID_LENGTH2 as MAX_CALL_ID_LENGTH, MAX_SAFE_INTEGER2 as MAX_SAFE_INTEGER, MIN_SAFE_INTEGER2 as MIN_SAFE_INTEGER, OperationMap2 as OperationMap, OperationMethod2 as OperationMethod, OperationShape2 as OperationShape, OperationTree2 as OperationTree, OperationsOf2 as OperationsOf, PLUGIN_DESCRIPTION_SCHEMA_VERSION2 as PLUGIN_DESCRIPTION_SCHEMA_VERSION, PluginDescription2 as PluginDescription, QGIS_SDK_MEMBERS2 as QGIS_SDK_MEMBERS, QgisSdk2 as QgisSdk, QgisSdkBridgeAbortedError2 as QgisSdkBridgeAbortedError, QgisSdkBridgeClosedError2 as QgisSdkBridgeClosedError, QgisSdkBridgeProtocolError2 as QgisSdkBridgeProtocolError, QgisSdkBridgeRemoteError2 as QgisSdkBridgeRemoteError, QgisSdkBridgeSequenceError2 as QgisSdkBridgeSequenceError, QgisSdkBridgeStreamEndedError2 as QgisSdkBridgeStreamEndedError, QgisSdkBridgeTimeoutError2 as QgisSdkBridgeTimeoutError, QgisSdkContractError, QgisSdkContractValidationError2 as QgisSdkContractValidationError, QgisSdkCore2 as QgisSdkCore, QgisSdkDeclarationError2 as QgisSdkDeclarationError, QgisSdkError2 as QgisSdkError, QgisSdkHost2 as QgisSdkHost, QgisSdkOptions2 as QgisSdkOptions, QgisSdkValidationIssue2 as QgisSdkValidationIssue, QgisSdkWebChannelError, SerializedContractError, SerializedContractValidationError2 as SerializedContractValidationError, SerializedValidationIssue2 as SerializedValidationIssue, StreamDescription2 as StreamDescription, StreamEventKind2 as StreamEventKind, StreamHandle2 as StreamHandle, StreamHandlers2 as StreamHandlers, StreamMap2 as StreamMap, StreamMethod2 as StreamMethod, StreamShape2 as StreamShape, StreamTerminalKind2 as StreamTerminalKind, StreamTree2 as StreamTree, StreamsOf2 as StreamsOf, SubscriptionHandlers2 as SubscriptionHandlers, ValidateOptions, ValidationDirection2 as ValidationDirection, WebChannelTransport, WireTransport2 as WireTransport, createWebChannelTransport, defineBridgeSchema2 as defineBridgeSchema, insideQgis, isSafeJsonInteger2 as isSafeJsonInteger, parseInvokeReply2 as parseInvokeReply, parsePluginDescription2 as parsePluginDescription, parseStreamFrame2 as parseStreamFrame, validateAgainstSchema };