@graphty/graph-io 0.3.47 → 0.3.49

package/dist/src/sources/codes.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The issue codes of network sources (design section 8). Every failure a source or the framework
+ * raises is an ImportIssue with one of these codes and machine-readable `params`; graph-io writes
+ * no reader-facing sentence. The English `message` is for logs.
+ *
+ * Experimental, with the source contract.
+ */
+/**
+ * Every issue code a network source can report, keyed by itself, so `SOURCE_ISSUE.E_SOURCE_AUTH`
+ * autocompletes and `keyof typeof SOURCE_ISSUE` is the code union. Experimental.
+ * @category Network sources
+ */
+export declare const SOURCE_ISSUE: Readonly<{
+    /** Another HTTP status, or an unreachable host (Node). Params: `url`, `status`. */
+    readonly E_FETCH: "E_FETCH";
+    /** The browser refused the request and hid why. Params: `url`, `cause`. */
+    readonly E_SOURCE_BLOCKED: "E_SOURCE_BLOCKED";
+    /** 401 or a database login failure. Params: `origin`, `status`, `scheme`, `serverCode`. */
+    readonly E_SOURCE_AUTH: "E_SOURCE_AUTH";
+    /** 403 or a database authorization failure. Params: `status`, `serverCode`. */
+    readonly E_SOURCE_FORBIDDEN: "E_SOURCE_FORBIDDEN";
+    /** The named item does not exist. Params: `what`, `value`. */
+    readonly E_SOURCE_NOT_FOUND: "E_SOURCE_NOT_FOUND";
+    /** 429 after the retries. Params: `retryAfterMs`. */
+    readonly E_SOURCE_QUOTA: "E_SOURCE_QUOTA";
+    /** `timeoutMs` passed, or the server's own timeout. Params: `timeoutMs`, `serverSide`. */
+    readonly E_SOURCE_TIMEOUT: "E_SOURCE_TIMEOUT";
+    /** The server rejected the query. Params: `serverCode`, `line`, `column`, `serverMessage`. */
+    readonly E_SOURCE_QUERY: "E_SOURCE_QUERY";
+    /** The result holds no node, relationship or path. Params: `columns`. */
+    readonly E_SOURCE_NOT_A_GRAPH: "E_SOURCE_NOT_A_GRAPH";
+    /** A response body of the wrong shape. Params: `expected`, `contentType`. */
+    readonly E_SOURCE_RESPONSE: "E_SOURCE_RESPONSE";
+    /** A redirect, or a changed origin, while a credential was attached. Params: `from`, `to`. */
+    readonly E_SOURCE_REDIRECT: "E_SOURCE_REDIRECT";
+    /** The source cannot run in this runtime. Params: `runtime`, `reason`, `package`. */
+    readonly E_SOURCE_RUNTIME: "E_SOURCE_RUNTIME";
+    /** A parameter or option is invalid. Params: `name`, `reason`. */
+    readonly E_SOURCE_PARAM: "E_SOURCE_PARAM";
+    /** A cap was reached under `onLimit: "error"`. Params: `limit`, `value`. */
+    readonly E_SOURCE_LIMIT: "E_SOURCE_LIMIT";
+    /** No source has that id. Params: `id`, `known`. */
+    readonly E_SOURCE_UNKNOWN: "E_SOURCE_UNKNOWN";
+    /** The source lacks the feature. Params: `feature`, `needs`. */
+    readonly E_SOURCE_UNSUPPORTED: "E_SOURCE_UNSUPPORTED";
+    /** A malformed source at registration. Params: `id`, `reason`. */
+    readonly E_SOURCE_INVALID: "E_SOURCE_INVALID";
+    /** A cap stopped the load; what came first is kept. Params: `limit`, `value`. */
+    readonly W_SOURCE_LIMIT: "W_SOURCE_LIMIT";
+    /** A later page needs a credential; the pages before it are kept. Params: `origin`, `status`. */
+    readonly W_SOURCE_AUTH: "W_SOURCE_AUTH";
+    /** The request succeeded after retries. Params: `attempts`, `statuses`. */
+    readonly W_SOURCE_RETRIED: "W_SOURCE_RETRIED";
+    /** A server value with no dtype. Params: `type`, `column`, `as`. */
+    readonly W_SOURCE_VALUE: "W_SOURCE_VALUE";
+}>;
+/**
+ * A network source issue code. Experimental.
+ * @category Network sources
+ */
+export type SourceIssueCode = keyof typeof SOURCE_ISSUE;
+/**
+ * Why `E_SOURCE_BLOCKED` was raised, as far as a page can tell. Open: handle unknown values.
+ * @category Network sources
+ */
+export type SourceBlockedCause = "cors" | "unreachable" | "local-network" | "unknown" | (string & {});
+/**
+ * The `params` of each source issue code. Every URL is origin and path only. Experimental.
+ * @category Network sources
+ */
+export interface SourceIssueParams {
+    /** Another status, or an unreachable host. */
+    readonly E_FETCH: {
+        /** The address, origin and path only. */
+        readonly url: string;
+        /** The HTTP status, or null when there was none. */
+        readonly status: number | null;
+    };
+    /** Refused by the browser. */
+    readonly E_SOURCE_BLOCKED: {
+        /** The address, origin and path only. */
+        readonly url: string;
+        /** Why, as far as the page can tell. */
+        readonly cause: SourceBlockedCause;
+    };
+    /** A credential is needed or was refused. */
+    readonly E_SOURCE_AUTH: {
+        /** The origin that asked for a credential. */
+        readonly origin: string;
+        /** The HTTP status, or null when there was none. */
+        readonly status: number | null;
+        /** The authentication scheme the server named, or null. */
+        readonly scheme: string | null;
+        /** The service's own code, passed through, or null. */
+        readonly serverCode: string | null;
+        /** Set by graphty-element when the credential came from its store. */
+        readonly stored?: boolean;
+    };
+    /** Not allowed. */
+    readonly E_SOURCE_FORBIDDEN: {
+        /** The HTTP status, or null when there was none. */
+        readonly status: number | null;
+        /** The service's own code, passed through, or null. */
+        readonly serverCode: string | null;
+    };
+    /** No such item. */
+    readonly E_SOURCE_NOT_FOUND: {
+        /** What was looked up (`url`, `network`, `node`). */
+        readonly what: string;
+        /** The value that reached the cap, or what was looked up. */
+        readonly value: string;
+    };
+    /** Out of quota. */
+    readonly E_SOURCE_QUOTA: {
+        /** How long the service asked to wait, when readable. */
+        readonly retryAfterMs: number | null;
+    };
+    /** Took too long. */
+    readonly E_SOURCE_TIMEOUT: {
+        /** The time limit, or null for the server's own. */
+        readonly timeoutMs: number | null;
+        /** Whether the server timed the query out. */
+        readonly serverSide: boolean;
+    };
+    /** The query was refused. */
+    readonly E_SOURCE_QUERY: {
+        /** The service's own code, passed through, or null. */
+        readonly serverCode: string | null;
+        /** The query line the server named, or null. */
+        readonly line: number | null;
+        /** The query column the server named, or null. */
+        readonly column: number | null;
+        /** The server's message from a JSON 4xx body, at most 500 characters, or null. */
+        readonly serverMessage: string | null;
+    };
+    /** Scalars only. */
+    readonly E_SOURCE_NOT_A_GRAPH: {
+        /** The result's column names. */
+        readonly columns: readonly string[];
+    };
+    /** Wrong body. */
+    readonly E_SOURCE_RESPONSE: {
+        /** What shape was expected (`json`, `graph-file`, `link-header`). */
+        readonly expected: string;
+        /** The response's Content-Type, or null. */
+        readonly contentType: string | null;
+    };
+    /** A redirect with a credential; `to` is null in a browser, which hides it. */
+    readonly E_SOURCE_REDIRECT: {
+        /** Where the request was going, origin and path. */
+        readonly from: string;
+        /** Where it was sent instead, or null when the browser hides it. */
+        readonly to: string | null;
+    };
+    /** Cannot run here. */
+    readonly E_SOURCE_RUNTIME: {
+        /** The runtime it ran in. */
+        readonly runtime: string;
+        /** Why, as a code. */
+        readonly reason: string;
+        /** The optional package that is missing. */
+        readonly package?: string;
+    };
+    /** A bad parameter or option. */
+    readonly E_SOURCE_PARAM: {
+        /** The parameter or option's name. */
+        readonly name: string;
+        /** Why, as a code. */
+        readonly reason: string;
+    };
+    /** A cap under onLimit "error". */
+    readonly E_SOURCE_LIMIT: {
+        /** The cap's option name (`maxNodes`, `maxBytes`, ...). */
+        readonly limit: string;
+        /** The value that reached the cap, or what was looked up. */
+        readonly value: number;
+    };
+    /** No such source. */
+    readonly E_SOURCE_UNKNOWN: {
+        /** The source id. */
+        readonly id: string;
+        /** The ids that are registered. */
+        readonly known: readonly string[];
+    };
+    /** The source lacks the feature. */
+    readonly E_SOURCE_UNSUPPORTED: {
+        /** The feature asked for. */
+        readonly feature: string;
+        /** What it needs, when known. */
+        readonly needs?: string;
+    };
+    /** A malformed source. */
+    readonly E_SOURCE_INVALID: {
+        /** The source id. */
+        readonly id: string;
+        /** Why, as a code. */
+        readonly reason: string;
+    };
+    /** A cap stopped the load. */
+    readonly W_SOURCE_LIMIT: {
+        /** The cap's option name (`maxNodes`, `maxBytes`, ...). */
+        readonly limit: string;
+        /** The value that reached the cap, or what was looked up. */
+        readonly value: number;
+    };
+    /** A later page needs a credential. */
+    readonly W_SOURCE_AUTH: {
+        /** The origin that asked for a credential. */
+        readonly origin: string;
+        /** The HTTP status, or null when there was none. */
+        readonly status: number | null;
+    };
+    /** Retried. */
+    readonly W_SOURCE_RETRIED: {
+        /** How many attempts were made. */
+        readonly attempts: number;
+        /** The status of each failed attempt, null for a network failure. */
+        readonly statuses: readonly (number | null)[];
+    };
+    /** A value with no dtype. */
+    readonly W_SOURCE_VALUE: {
+        /** The server's value type. */
+        readonly type: string;
+        /** The column (of the query, or of the graph) involved. */
+        readonly column: string;
+        /** What the value was kept as. */
+        readonly as: string;
+    };
+}
+//# sourceMappingURL=codes.d.ts.map

package/dist/src/sources/codes.d.ts.map

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

package/dist/src/sources/codes.js

@@ -0,0 +1,58 @@
+/**
+ * The issue codes of network sources (design section 8). Every failure a source or the framework
+ * raises is an ImportIssue with one of these codes and machine-readable `params`; graph-io writes
+ * no reader-facing sentence. The English `message` is for logs.
+ *
+ * Experimental, with the source contract.
+ */
+import { FETCH_CODE } from "../common/codes.js";
+/**
+ * Every issue code a network source can report, keyed by itself, so `SOURCE_ISSUE.E_SOURCE_AUTH`
+ * autocompletes and `keyof typeof SOURCE_ISSUE` is the code union. Experimental.
+ * @category Network sources
+ */
+export const SOURCE_ISSUE = Object.freeze({
+    /** Another HTTP status, or an unreachable host (Node). Params: `url`, `status`. */
+    E_FETCH: FETCH_CODE,
+    /** The browser refused the request and hid why. Params: `url`, `cause`. */
+    E_SOURCE_BLOCKED: "E_SOURCE_BLOCKED",
+    /** 401 or a database login failure. Params: `origin`, `status`, `scheme`, `serverCode`. */
+    E_SOURCE_AUTH: "E_SOURCE_AUTH",
+    /** 403 or a database authorization failure. Params: `status`, `serverCode`. */
+    E_SOURCE_FORBIDDEN: "E_SOURCE_FORBIDDEN",
+    /** The named item does not exist. Params: `what`, `value`. */
+    E_SOURCE_NOT_FOUND: "E_SOURCE_NOT_FOUND",
+    /** 429 after the retries. Params: `retryAfterMs`. */
+    E_SOURCE_QUOTA: "E_SOURCE_QUOTA",
+    /** `timeoutMs` passed, or the server's own timeout. Params: `timeoutMs`, `serverSide`. */
+    E_SOURCE_TIMEOUT: "E_SOURCE_TIMEOUT",
+    /** The server rejected the query. Params: `serverCode`, `line`, `column`, `serverMessage`. */
+    E_SOURCE_QUERY: "E_SOURCE_QUERY",
+    /** The result holds no node, relationship or path. Params: `columns`. */
+    E_SOURCE_NOT_A_GRAPH: "E_SOURCE_NOT_A_GRAPH",
+    /** A response body of the wrong shape. Params: `expected`, `contentType`. */
+    E_SOURCE_RESPONSE: "E_SOURCE_RESPONSE",
+    /** A redirect, or a changed origin, while a credential was attached. Params: `from`, `to`. */
+    E_SOURCE_REDIRECT: "E_SOURCE_REDIRECT",
+    /** The source cannot run in this runtime. Params: `runtime`, `reason`, `package`. */
+    E_SOURCE_RUNTIME: "E_SOURCE_RUNTIME",
+    /** A parameter or option is invalid. Params: `name`, `reason`. */
+    E_SOURCE_PARAM: "E_SOURCE_PARAM",
+    /** A cap was reached under `onLimit: "error"`. Params: `limit`, `value`. */
+    E_SOURCE_LIMIT: "E_SOURCE_LIMIT",
+    /** No source has that id. Params: `id`, `known`. */
+    E_SOURCE_UNKNOWN: "E_SOURCE_UNKNOWN",
+    /** The source lacks the feature. Params: `feature`, `needs`. */
+    E_SOURCE_UNSUPPORTED: "E_SOURCE_UNSUPPORTED",
+    /** A malformed source at registration. Params: `id`, `reason`. */
+    E_SOURCE_INVALID: "E_SOURCE_INVALID",
+    /** A cap stopped the load; what came first is kept. Params: `limit`, `value`. */
+    W_SOURCE_LIMIT: "W_SOURCE_LIMIT",
+    /** A later page needs a credential; the pages before it are kept. Params: `origin`, `status`. */
+    W_SOURCE_AUTH: "W_SOURCE_AUTH",
+    /** The request succeeded after retries. Params: `attempts`, `statuses`. */
+    W_SOURCE_RETRIED: "W_SOURCE_RETRIED",
+    /** A server value with no dtype. Params: `type`, `column`, `as`. */
+    W_SOURCE_VALUE: "W_SOURCE_VALUE",
+});
+//# sourceMappingURL=codes.js.map

package/dist/src/sources/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../src/sources/codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;IACtC,mFAAmF;IACnF,OAAO,EAAE,UAAU;IACnB,2EAA2E;IAC3E,gBAAgB,EAAE,kBAAkB;IACpC,2FAA2F;IAC3F,aAAa,EAAE,eAAe;IAC9B,+EAA+E;IAC/E,kBAAkB,EAAE,oBAAoB;IACxC,8DAA8D;IAC9D,kBAAkB,EAAE,oBAAoB;IACxC,qDAAqD;IACrD,cAAc,EAAE,gBAAgB;IAChC,0FAA0F;IAC1F,gBAAgB,EAAE,kBAAkB;IACpC,8FAA8F;IAC9F,cAAc,EAAE,gBAAgB;IAChC,yEAAyE;IACzE,oBAAoB,EAAE,sBAAsB;IAC5C,6EAA6E;IAC7E,iBAAiB,EAAE,mBAAmB;IACtC,8FAA8F;IAC9F,iBAAiB,EAAE,mBAAmB;IACtC,qFAAqF;IACrF,gBAAgB,EAAE,kBAAkB;IACpC,kEAAkE;IAClE,cAAc,EAAE,gBAAgB;IAChC,4EAA4E;IAC5E,cAAc,EAAE,gBAAgB;IAChC,oDAAoD;IACpD,gBAAgB,EAAE,kBAAkB;IACpC,gEAAgE;IAChE,oBAAoB,EAAE,sBAAsB;IAC5C,kEAAkE;IAClE,gBAAgB,EAAE,kBAAkB;IACpC,iFAAiF;IACjF,cAAc,EAAE,gBAAgB;IAChC,iGAAiG;IACjG,aAAa,EAAE,eAAe;IAC9B,2EAA2E;IAC3E,gBAAgB,EAAE,kBAAkB;IACpC,oEAAoE;IACpE,cAAc,EAAE,gBAAgB;CAC1B,CAAC,CAAC"}

package/dist/src/sources/context.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The source context (design sections 2.1, 6.2, 7.2 and 9): the guarded `ctx.fetch` every source
+ * reads through. It applies the credential only to the origins it is bound to, refuses credentials
+ * in clear text and across redirects, retries what HTTP says is safe to retry, paces requests,
+ * enforces the caps, counts decoded bytes, times the load out and turns every failure into a coded
+ * issue. A source never sees the credential.
+ */
+import { type ImportReportBuilder } from "../common/report.js";
+import { type LoadFromSourceOptions, type SourceContext, type SourceCursor, type SourceDescriptor, type SourceFinish, type SourceReportInfo, type SourceRuntime } from "./types.js";
+/**
+ * Thrown inside a load when a cap stops it under `onLimit: "stop"`; the runner catches it, keeps
+ * what came first and records where to resume. Never leaves graph-io.
+ */
+export declare class LimitStop extends Error {
+    readonly limit: string;
+    readonly value: number;
+    /**
+     * Create one.
+     * @param limit - the cap's option name
+     * @param value - the value that reached it
+     */
+    constructor(limit: string, value: number);
+}
+/**
+ * Where code is running. Node is checked first, since a test may stub a `document`.
+ * @returns the runtime
+ */
+export declare function detectRuntime(): SourceRuntime;
+/**
+ * Whether a host is this machine.
+ * @param hostname - the URL's hostname
+ * @returns true for localhost, 127.0.0.0/8 and ::1
+ */
+export declare function isLoopback(hostname: string): boolean;
+/**
+ * Whether a host is on a local network: loopback, private IPv4 ranges, link-local, unique local
+ * IPv6 or an mDNS `.local` name.
+ * @param hostname - the URL's hostname
+ * @returns true for a local-network host
+ */
+export declare function isLocalNetwork(hostname: string): boolean;
+/** What the runner reads back from a context after a load. */
+export interface ContextState {
+    /** Requests sent. */
+    requests: number;
+    /** Decoded response bytes read. */
+    bytes: number;
+    /** What the source passed to finish(). */
+    finish: SourceFinish | null;
+}
+/** What createSourceContext() needs. */
+interface ContextInput {
+    /** The source id. */
+    readonly id: string;
+    /** The source's descriptor, if it has one. */
+    readonly descriptor: SourceDescriptor | undefined;
+    /** The caller's options. */
+    readonly options: LoadFromSourceOptions;
+    /** The load's report. */
+    readonly report: ImportReportBuilder;
+    /** The resolved endpoint. */
+    readonly endpoint: URL | null;
+    /** The cursor the source sees (version stripped). */
+    readonly cursor: SourceCursor | null;
+    /** What progress counts: "bytes" for a file source, "items" otherwise. */
+    readonly unit: "items" | "bytes";
+    /** What the sink has received so far. */
+    readonly counts: () => {
+        readonly nodes: number;
+        readonly edges: number;
+    };
+    /** The runtime to act as; detected when absent (tests set it). */
+    readonly runtime?: SourceRuntime | undefined;
+}
+/** A context and what the runner needs to close it. */
+export interface CreatedContext {
+    /** The context handed to the source. */
+    readonly ctx: SourceContext;
+    /** Counters the runner reads. */
+    readonly state: ContextState;
+    /**
+     * The report's `source` member as it stands.
+     * @param next - where to resume
+     * @returns the info
+     */
+    info(next: SourceCursor | null): SourceReportInfo;
+    /** Clear the timeout and detach from the caller's signal. */
+    dispose(): void;
+}
+/**
+ * Wait, unless the signal aborts first.
+ * @param ms - milliseconds
+ * @param signal - the signal
+ * @returns a promise that settles after the wait
+ */
+export declare function sleep(ms: number, signal: AbortSignal): Promise<void>;
+/**
+ * The credential and transport options of a context's load. Internal to graph-io: a transport that
+ * hands a credential to a driver (Bolt) reads it here and applies the origin and TLS rules itself.
+ * Sources outside graph-io never see a credential.
+ * @param ctx - the context
+ * @returns the options that matter to a transport
+ */
+export declare function transportOptions(ctx: SourceContext): Pick<LoadFromSourceOptions, "credential" | "allowInsecure" | "userAgent">;
+/**
+ * Create the context of one source call.
+ * @param input - the source, options, report and counters
+ * @returns the context and its controls
+ */
+export declare function createSourceContext(input: ContextInput): CreatedContext;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/src/sources/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/sources/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAK/D,OAAO,EAEH,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAGjB,KAAK,gBAAgB,EAErB,KAAK,aAAa,EACrB,MAAM,YAAY,CAAC;AAcpB;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAO5B,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM;IAP1B;;;;OAIG;gBAEU,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM;CAK7B;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,aAAa,CAc7C;AAWD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAYxD;AAYD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IACzB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CAC/B;AAED,wCAAwC;AACxC,UAAU,YAAY;IAClB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAClD,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACjC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAChD;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,gBAAgB,CAAC;IAClD,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBpE;AAuoBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,aAAa,GACnB,IAAI,CAAC,qBAAqB,EAAE,YAAY,GAAG,eAAe,GAAG,WAAW,CAAC,CAG3E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CA6BvE"}