@honua/app-platform 0.0.20-alpha.0

package/core/process-runner.d.ts

@@ -0,0 +1,104 @@
+import type { IJobRun } from "../contract/jobs.js";
+import type { HonuaOgcProcesses } from "./ogc-processes.js";
+import type { HonuaGeoprocessingService } from "./surfaces.js";
+import type { OgcProcessExecuteRequest } from "./types.js";
+export type HonuaProcessProtocol = "ogc-processes" | "geoservices-gp" | "geospatial-grpc";
+export interface HonuaProcessExecuteRequest {
+    /** OGC process id or a human-readable id for GP/gRPC plans. */
+    readonly processId?: string;
+    /** OGC-style input bag, also used as GPServer submit parameters by the GeoServices adapter. */
+    readonly inputs?: OgcProcessExecuteRequest["inputs"];
+    /** GeoServices GPServer submit parameters. Takes precedence over `inputs`. */
+    readonly parameters?: Record<string, unknown>;
+    /** geospatial-grpc `ExecutionPlan` message or compatible plain object. */
+    readonly plan?: unknown;
+    /** OGC output descriptor map, when targeting OGC API Processes. */
+    readonly outputs?: OgcProcessExecuteRequest["outputs"];
+    /** geospatial-grpc `ExecutionContext` message or compatible plain object. */
+    readonly context?: unknown;
+    /** Result ids to fetch when targeting GeoServices GPServer result routes. */
+    readonly resultNames?: readonly string[];
+    readonly mode?: "async" | "auto";
+    readonly signal?: AbortSignal;
+}
+export interface HonuaProcessJobOptions {
+    readonly processId?: string;
+    readonly resultNames?: readonly string[];
+}
+export interface HonuaProcessAdapter {
+    readonly protocol: HonuaProcessProtocol;
+    execute<T = unknown>(request: HonuaProcessExecuteRequest): Promise<IJobRun<T>>;
+    job<T = unknown>(jobId: string, options?: HonuaProcessJobOptions): IJobRun<T>;
+    validate?(request: HonuaProcessExecuteRequest): Promise<unknown>;
+    dryRun?(request: HonuaProcessExecuteRequest): Promise<unknown>;
+}
+export declare class HonuaProcessRunner {
+    readonly adapter: HonuaProcessAdapter;
+    constructor(adapter: HonuaProcessAdapter);
+    get protocol(): HonuaProcessProtocol;
+    execute<T = unknown>(request: HonuaProcessExecuteRequest): Promise<IJobRun<T>>;
+    job<T = unknown>(jobId: string, options?: HonuaProcessJobOptions): IJobRun<T>;
+    validate(request: HonuaProcessExecuteRequest): Promise<unknown>;
+    dryRun(request: HonuaProcessExecuteRequest): Promise<unknown>;
+}
+export declare function createHonuaProcessRunner(adapter: HonuaProcessAdapter): HonuaProcessRunner;
+export declare function createOgcProcessesAdapter(processes: HonuaOgcProcesses): HonuaProcessAdapter;
+export declare function createGeoServicesGpAdapter(service: HonuaGeoprocessingService): HonuaProcessAdapter;
+export interface GeospatialGrpcProcessClient {
+    validatePlan?(request: {
+        readonly plan: unknown;
+    }): Promise<unknown>;
+    dryRunPlan?(request: {
+        readonly plan: unknown;
+    }): Promise<unknown>;
+    submitJob(request: {
+        readonly plan: unknown;
+        readonly context?: unknown;
+    }): Promise<GeospatialGrpcSubmitJobResponse>;
+    getJob(request: {
+        readonly jobId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<GeospatialGrpcGetJobResponse>;
+    getJobResult(request: {
+        readonly jobId: string;
+    }): Promise<GeospatialGrpcGetJobResultResponse>;
+    cancelJob(request: {
+        readonly jobId: string;
+    }): Promise<GeospatialGrpcCancelJobResponse>;
+}
+export interface GeospatialGrpcSubmitJobResponse {
+    readonly jobId?: string;
+    readonly job_id?: string;
+    readonly state?: unknown;
+}
+export interface GeospatialGrpcGetJobResponse extends GeospatialGrpcSubmitJobResponse {
+    readonly progress?: GeospatialGrpcJobProgress;
+}
+export interface GeospatialGrpcCancelJobResponse extends GeospatialGrpcSubmitJobResponse {
+}
+export interface GeospatialGrpcGetJobResultResponse {
+    readonly jobId?: string;
+    readonly job_id?: string;
+    readonly result?: unknown;
+    readonly error?: GeospatialGrpcErrorDetail;
+    readonly outcome?: {
+        readonly case?: string;
+        readonly value?: unknown;
+    };
+}
+export interface GeospatialGrpcJobProgress {
+    readonly progressPercent?: number;
+    readonly progress_percent?: number;
+    readonly message?: string;
+    readonly updatedAt?: number | bigint | string;
+    readonly updated_at?: number | bigint | string;
+    readonly state?: unknown;
+}
+export interface GeospatialGrpcErrorDetail {
+    readonly errorCode?: string;
+    readonly error_code?: string;
+    readonly message?: string;
+    readonly details?: Record<string, string>;
+}
+export declare function createGeospatialGrpcProcessAdapter(client: GeospatialGrpcProcessClient): HonuaProcessAdapter;
+//# sourceMappingURL=process-runner.d.ts.map

package/core/process-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-runner.d.ts","sourceRoot":"","sources":["../../../src/core/process-runner.ts"],"names":[],"mappings":"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"}

package/core/process-runner.js

@@ -0,0 +1,315 @@
+import { HonuaJobPollTimeoutError } from "../contract/jobs.js";
+export class HonuaProcessRunner {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    get protocol() {
+        return this.adapter.protocol;
+    }
+    execute(request) {
+        return this.adapter.execute(request);
+    }
+    job(jobId, options = {}) {
+        return this.adapter.job(jobId, options);
+    }
+    async validate(request) {
+        if (!this.adapter.validate) {
+            throw new Error(`${this.protocol} does not expose validate through the unified process runner.`);
+        }
+        return this.adapter.validate(request);
+    }
+    async dryRun(request) {
+        if (!this.adapter.dryRun) {
+            throw new Error(`${this.protocol} does not expose dryRun through the unified process runner.`);
+        }
+        return this.adapter.dryRun(request);
+    }
+}
+export function createHonuaProcessRunner(adapter) {
+    return new HonuaProcessRunner(adapter);
+}
+export function createOgcProcessesAdapter(processes) {
+    return {
+        protocol: "ogc-processes",
+        execute(request) {
+            if (!request.processId)
+                throw new Error("OGC Processes execution requires processId.");
+            return processes.execute({
+                processId: request.processId,
+                inputs: request.inputs,
+                outputs: request.outputs,
+                mode: request.mode ?? "async",
+                signal: request.signal,
+            });
+        },
+        job(jobId, options = {}) {
+            return processes.job(jobId, { processId: options.processId });
+        },
+    };
+}
+export function createGeoServicesGpAdapter(service) {
+    return {
+        protocol: "geoservices-gp",
+        execute(request) {
+            return service.submit({
+                parameters: request.parameters ?? request.inputs ?? {},
+                signal: request.signal,
+            }, { resultNames: request.resultNames });
+        },
+        job(jobId, options = {}) {
+            return service.job(jobId, { resultNames: options.resultNames });
+        },
+    };
+}
+export function createGeospatialGrpcProcessAdapter(client) {
+    return {
+        protocol: "geospatial-grpc",
+        validate(request) {
+            if (!client.validatePlan)
+                throw new Error("geospatial-grpc ProcessService client does not expose validatePlan.");
+            return client.validatePlan({ plan: requirePlan(request) });
+        },
+        dryRun(request) {
+            if (!client.dryRunPlan)
+                throw new Error("geospatial-grpc ProcessService client does not expose dryRunPlan.");
+            return client.dryRunPlan({ plan: requirePlan(request) });
+        },
+        async execute(request) {
+            const accepted = await client.submitJob({ plan: requirePlan(request), context: request.context });
+            return new GeospatialGrpcProcessJobRun({ client, accepted });
+        },
+        job(jobId) {
+            return new GeospatialGrpcProcessJobRun({ client, accepted: { jobId, state: "JOB_STATE_UNSPECIFIED" } });
+        },
+    };
+}
+class GeospatialGrpcProcessJobRun {
+    id;
+    type = "geospatial-grpc";
+    client;
+    currentStatus;
+    currentProgress;
+    terminalSnapshot;
+    terminalPromise;
+    listeners = new Set();
+    constructor(options) {
+        this.client = options.client;
+        this.id = readJobId(options.accepted);
+        this.currentStatus = geospatialGrpcJobStateToStatus(options.accepted.state);
+    }
+    get status() {
+        return this.currentStatus;
+    }
+    get progress() {
+        return this.currentProgress;
+    }
+    async poll() {
+        if (this.terminalSnapshot)
+            return this.terminalSnapshot;
+        const response = await this.client.getJob({ jobId: this.id });
+        return this.handleJob(response);
+    }
+    watch(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async results(options = {}) {
+        if (!this.terminalPromise) {
+            // Reset on failure so an aborted / timed-out poll does not permanently
+            // poison subsequent results() calls.
+            this.terminalPromise = this.runUntilTerminal(options).catch((error) => {
+                this.terminalPromise = undefined;
+                throw error;
+            });
+        }
+        return this.terminalPromise;
+    }
+    async cancel() {
+        if (this.terminalSnapshot)
+            return this.currentStatus;
+        const response = await this.client.cancelJob({ jobId: this.id });
+        const snapshot = await this.handleJob(response);
+        return snapshot.status;
+    }
+    async runUntilTerminal(options = {}) {
+        const { signal } = options;
+        const baseIntervalMs = options.pollIntervalMs ?? 1_000;
+        const maxIntervalMs = options.maxPollIntervalMs ?? Math.max(baseIntervalMs, 30_000);
+        const startedAt = Date.now();
+        let attempts = 0;
+        while (!this.terminalSnapshot) {
+            if (signal?.aborted) {
+                throw new HonuaJobPollTimeoutError(`Job ${this.id} poll aborted`, "aborted", this.id, this.currentStatus);
+            }
+            if (options.maxAttempts !== undefined && attempts >= options.maxAttempts) {
+                throw new HonuaJobPollTimeoutError(`Job ${this.id} did not reach a terminal state within ${options.maxAttempts} poll attempt(s)`, "max-attempts", this.id, this.currentStatus);
+            }
+            let response;
+            try {
+                response = await this.client.getJob({ jobId: this.id, signal });
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    throw new HonuaJobPollTimeoutError(`Job ${this.id} poll aborted`, "aborted", this.id, this.currentStatus);
+                }
+                throw error;
+            }
+            attempts += 1;
+            await this.handleJob(response);
+            if (this.terminalSnapshot)
+                break;
+            if (options.deadlineMs !== undefined && Date.now() - startedAt >= options.deadlineMs) {
+                throw new HonuaJobPollTimeoutError(`Job ${this.id} did not reach a terminal state within ${options.deadlineMs}ms`, "deadline", this.id, this.currentStatus);
+            }
+            // Capped exponential backoff instead of a fixed 1s interval.
+            const intervalMs = Math.min(maxIntervalMs, baseIntervalMs * 2 ** (attempts - 1));
+            if (intervalMs > 0) {
+                await wait(intervalMs, signal);
+            }
+        }
+        if (this.terminalSnapshot.status === "successful" && this.terminalSnapshot.result) {
+            return this.terminalSnapshot.result;
+        }
+        throw new Error(this.terminalSnapshot.error?.message ?? `geospatial-grpc job ended in ${this.terminalSnapshot.status}`);
+    }
+    async handleJob(response) {
+        const jobProgress = "progress" in response ? response.progress : undefined;
+        const status = geospatialGrpcJobStateToStatus(response.state ?? jobProgress?.state);
+        const progress = geospatialGrpcProgress(jobProgress);
+        this.currentStatus = status;
+        this.currentProgress = progress;
+        if (status === "successful") {
+            const result = await this.client.getJobResult({ jobId: this.id });
+            const snapshot = geospatialGrpcResultSnapshot(result, progress);
+            this.terminalSnapshot = snapshot;
+            this.currentStatus = snapshot.status;
+            this.notify(snapshot);
+            return snapshot;
+        }
+        if (status === "failed" || status === "dismissed") {
+            const result = await this.safeGetTerminalResult();
+            const error = result ? geospatialGrpcError(result) : undefined;
+            const snapshot = { status, progress, ...(error ? { error } : {}) };
+            this.terminalSnapshot = snapshot;
+            this.notify(snapshot);
+            return snapshot;
+        }
+        const snapshot = { status, progress };
+        this.notify(snapshot);
+        return snapshot;
+    }
+    async safeGetTerminalResult() {
+        try {
+            return await this.client.getJobResult({ jobId: this.id });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    notify(snapshot) {
+        for (const listener of this.listeners)
+            listener(snapshot);
+    }
+}
+function requirePlan(request) {
+    if (request.plan === undefined)
+        throw new Error("geospatial-grpc process execution requires plan.");
+    return request.plan;
+}
+function readJobId(response) {
+    const jobId = response.jobId ?? response.job_id;
+    if (!jobId)
+        throw new Error("ProcessService response did not include jobId.");
+    return jobId;
+}
+function geospatialGrpcJobStateToStatus(value) {
+    if (value === 6)
+        return "successful";
+    if (value === 7)
+        return "failed";
+    if (value === 8)
+        return "dismissed";
+    if (value === 5)
+        return "running";
+    if (value === 1 || value === 2 || value === 3 || value === 4)
+        return "accepted";
+    const normalized = String(value ?? "").toLowerCase();
+    if (normalized.includes("completed") || normalized === "successful")
+        return "successful";
+    if (normalized.includes("failed"))
+        return "failed";
+    if (normalized.includes("cancelled") || normalized.includes("canceled") || normalized.includes("dismissed")) {
+        return "dismissed";
+    }
+    if (normalized.includes("draft") ||
+        normalized.includes("clarification") ||
+        normalized.includes("validated") ||
+        normalized.includes("approval") ||
+        normalized.includes("accepted")) {
+        return "accepted";
+    }
+    if (normalized.includes("running"))
+        return "running";
+    return "accepted";
+}
+function geospatialGrpcProgress(progress) {
+    if (!progress)
+        return undefined;
+    const percent = progress.progressPercent ?? progress.progress_percent;
+    const updatedAt = progress.updatedAt ?? progress.updated_at;
+    const out = {};
+    if (typeof percent === "number" && Number.isFinite(percent))
+        out.percent = Math.max(0, Math.min(100, percent));
+    if (progress.message)
+        out.message = progress.message;
+    if (updatedAt !== undefined)
+        out.updatedAt = timestampToIso(updatedAt);
+    return out.percent === undefined && out.message === undefined && out.updatedAt === undefined ? undefined : out;
+}
+function geospatialGrpcResultSnapshot(response, progress) {
+    const error = geospatialGrpcError(response);
+    if (error)
+        return { status: "failed", progress, error };
+    return {
+        status: "successful",
+        progress,
+        result: {
+            outputs: { result: (response.result ?? response.outcome?.value ?? response) },
+        },
+    };
+}
+function geospatialGrpcError(response) {
+    const candidate = response.error ??
+        (response.outcome?.case === "error" ? response.outcome.value : undefined);
+    if (!candidate)
+        return undefined;
+    return {
+        code: candidate.errorCode ?? candidate.error_code ?? "GeospatialGrpcProcessError",
+        message: candidate.message ?? "geospatial-grpc process execution failed.",
+        details: candidate.details,
+    };
+}
+function timestampToIso(value) {
+    const numeric = typeof value === "bigint" ? Number(value) : typeof value === "string" ? Number(value) : value;
+    if (Number.isFinite(numeric))
+        return new Date(numeric).toISOString();
+    return String(value);
+}
+function wait(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/core/protocol-transport.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Low-level transport surface consumed by the per-protocol wire modules.
+ *
+ * `HonuaClient` owns the request/retry/auth/cache pipeline (see
+ * `executeRequest` and `request-pipeline.ts`); each protocol family
+ * (OGC API Features/Tiles/Maps/Records/Processes, STAC, WMS, WMTS, and the
+ * GeoServices map/feature endpoints) builds its own URLs, serializes its own
+ * params, and parses its own responses against this injected transport rather
+ * than reaching into the client. The client exposes a single object that
+ * satisfies this interface and hands it to the wire functions, keeping the
+ * client a thin facade over the protocol modules.
+ *
+ * @module
+ */
+import type { HonuaMetadataRequestOptions } from "./cache-state.js";
+import type { QueryMethod } from "./types.js";
+/**
+ * The minimal request primitives a protocol wire module needs. Every method
+ * routes through the same auth / retry / timeout / interceptor pipeline as the
+ * rest of the SDK; wire modules never call `fetch` directly.
+ */
+export interface HonuaProtocolTransport {
+    /**
+     * Normalized base URL (trailing slashes trimmed). Pure URL-template builders
+     * (e.g. MapLibre tile sources) read this to produce the same origin/base path
+     * the server is served from.
+     */
+    readonly baseUrl: string;
+    /**
+     * Pipeline-aware JSON request. Sends `Accept: application/json` by default and
+     * surfaces GeoServices `{error}` envelopes returned on HTTP 200 as
+     * `HonuaHttpError`. Caller-supplied query params belong on `path`.
+     */
+    requestJson<T = unknown>(method: QueryMethod, path: string, init?: RequestInit, signal?: AbortSignal): Promise<T>;
+    /**
+     * Fetch a text response (XML / JSON / plain) with explicit Accept negotiation.
+     * Used by the WMS / WMTS capabilities pipelines and the WFS adapter.
+     */
+    requestText(method: QueryMethod, path: string, options?: {
+        accept?: string;
+        contentType?: string;
+        body?: BodyInit;
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        contentType: string;
+        status: number;
+    }>;
+    /**
+     * Fetch a binary response (raw bytes plus content type). Used by the OGC API
+     * Tiles / Maps and WMS / WMTS wire methods that negotiate non-JSON formats.
+     */
+    requestBytes(method: QueryMethod, path: string, accept: string | undefined, init?: RequestInit, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+        empty: boolean;
+    }>;
+    /**
+     * Cached metadata GET. Honors the metadata cache (`hit`/`miss`/`stale`/
+     * `refreshed`/`bypass`), conditional revalidation, and stale-if-error.
+     */
+    requestCachedMetadataJson<T>(cacheKey: string, path: string, options?: HonuaMetadataRequestOptions): Promise<T>;
+    /**
+     * Pipeline-aware request returning the raw, unconsumed `Response` after the
+     * shared pipeline succeeds. Callers pick `.json()` / `.text()` / `.arrayBuffer()`.
+     */
+    pipelineFetch(method: QueryMethod, path: string, init?: RequestInit, callerSignal?: AbortSignal, options?: {
+        okStatuses?: readonly number[];
+    }): Promise<Response>;
+    /**
+     * Request a PBF binary response and decode it, transparently falling back to
+     * `f=json` on decode failure. Used by the GeoServices feature query fast path.
+     */
+    requestBinaryWithJsonFallback<T = unknown>(method: QueryMethod, path: string, params: URLSearchParams, signal?: AbortSignal): Promise<T>;
+}
+//# sourceMappingURL=protocol-transport.d.ts.map

package/core/protocol-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-transport.d.ts","sourceRoot":"","sources":["../../../src/core/protocol-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAElH;;;OAGG;IACH,WAAW,CACT,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACzF,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAElE;;;OAGG;IACH,YAAY,CACV,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,CAAC,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAEvE;;;OAGG;IACH,yBAAyB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEhH;;;OAGG;IACH,aAAa,CACX,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,WAAW,EAC1B,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAC3C,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB;;;OAGG;IACH,6BAA6B,CAAC,CAAC,GAAG,OAAO,EACvC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf"}

package/core/protocol-transport.js

@@ -0,0 +1,15 @@
+/**
+ * Low-level transport surface consumed by the per-protocol wire modules.
+ *
+ * `HonuaClient` owns the request/retry/auth/cache pipeline (see
+ * `executeRequest` and `request-pipeline.ts`); each protocol family
+ * (OGC API Features/Tiles/Maps/Records/Processes, STAC, WMS, WMTS, and the
+ * GeoServices map/feature endpoints) builds its own URLs, serializes its own
+ * params, and parses its own responses against this injected transport rather
+ * than reaching into the client. The client exposes a single object that
+ * satisfies this interface and hands it to the wire functions, keeping the
+ * client a thin facade over the protocol modules.
+ *
+ * @module
+ */
+export {};