@graphty/graph-io 0.3.46 → 0.3.48

package/src/registry.ts

@@ -13,6 +13,7 @@ import {
     GraphBuilder,
     type GraphBuilderOptions,
     GraphFormatError,
+    type GraphSink,
     type GraphSnapshot,
 } from "@graphty/graph-format";
 
@@ -46,6 +47,21 @@ import { oboExporter, oboImporter } from "./formats/obo/index.js";
 import { pajekExporter, pajekImporter } from "./formats/pajek/index.js";
 import { xgmmlExporter, xgmmlImporter } from "./formats/xgmml/index.js";
 import { type FormatName, rankFormats, SNIFF_HEAD_BYTES, type SniffHints, type SniffResult } from "./sniff.js";
+import { builtinSources } from "./sources/builtins.js";
+import { type SourceParamsMap } from "./sources/params.js";
+import { SourceRegistry } from "./sources/registry.js";
+import {
+    type ExpandRequest,
+    type GraphSource,
+    type LazySource,
+    type LoadFromSourceOptions,
+    type SourceFreshness,
+    type SourceInfo,
+    type SourceListing,
+    type SourceListQuery,
+    type SourceProbe,
+    type SourceValidators,
+} from "./sources/types.js";
 import { extractStyles, type StyleImportOptions } from "./styles/io/generic.js";
 import { isKeptGraphtyProperty, prepareStyleExport } from "./styles/io/writer.js";
 import type { ExtractedStyles } from "./styles/types.js";
@@ -323,6 +339,150 @@ export class FormatRegistry {
 
     private readonly exporterMap = new Map<string, GraphExporter>();
 
+    private readonly sources = new SourceRegistry(this, {
+        newBuilder: (options, format) => seededBuilder(options as ImportGraphOptions, format),
+        freeze: (format, builder, report, options) =>
+            result(
+                { importer: { format } as GraphImporter, sniff: null, source: "", peeked: null, warnings: [] },
+                builder,
+                report,
+                options as ImportGraphOptions,
+            ),
+    });
+
+    /**
+     * Register a network source, or a lazy one whose code loads on first use. Source ids are their
+     * own name space, apart from format names. Throws an ImportError with E_SOURCE_INVALID for a
+     * malformed source or an id already taken. Experimental.
+     * @param source - the source
+     * @returns this registry
+     */
+    registerSource<P>(source: GraphSource<P> | LazySource): this {
+        this.sources.register(source);
+        return this;
+    }
+
+    /**
+     * A registered source by id, its code loaded. Rejects with E_SOURCE_UNKNOWN for an id no
+     * source has. Experimental.
+     * @param id - the source id
+     * @returns the source
+     */
+    source(id: string): Promise<GraphSource<never>> {
+        return this.sources.resolve(id);
+    }
+
+    /**
+     * Whether a source id is registered. Experimental.
+     * @param id - the source id
+     * @returns true when registered
+     */
+    hasSource(id: string): boolean {
+        return this.sources.has(id);
+    }
+
+    /**
+     * Every registered source with its descriptor, loading no source code. Experimental.
+     * @returns one entry per source
+     */
+    listSources(): readonly SourceInfo[] {
+        return this.sources.list();
+    }
+
+    /**
+     * Load a graph from a network source; see the top-level loadFromSource(). Experimental.
+     * @param source - the source id or the source
+     * @param params - its params
+     * @param options - endpoint, credential, cursor, caps and import options
+     * @returns the graph and the report
+     */
+    loadFromSource(
+        source: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        options?: LoadFromSourceOptions,
+    ): Promise<ImportGraphResult> {
+        return this.sources.load(source, params, options);
+    }
+
+    /**
+     * Load from a network source into a sink you own. Experimental.
+     * @param source - the source id or the source
+     * @param params - its params
+     * @param sink - where to write
+     * @param options - the options
+     * @returns the report
+     */
+    importFromSource(
+        source: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        sink: GraphSink,
+        options?: LoadFromSourceOptions,
+    ): Promise<ImportReport> {
+        return this.sources.import(source, params, sink, options);
+    }
+
+    /**
+     * Fetch the neighborhood of some nodes from a network source. Experimental.
+     * @param source - the source id or the source
+     * @param request - the seeds and how far to go
+     * @param options - the options
+     * @returns a graph of only what was fetched
+     */
+    expandFromSource(
+        source: string | GraphSource<never>,
+        request: ExpandRequest<Readonly<Record<string, unknown>>>,
+        options?: LoadFromSourceOptions,
+    ): Promise<ImportGraphResult> {
+        return this.sources.expand(source, request, options);
+    }
+
+    /**
+     * Check a source's params and credential without loading. Experimental.
+     * @param source - the source id or the source
+     * @param params - its params
+     * @param options - the options
+     * @returns what the service said
+     */
+    probeSource(
+        source: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        options?: LoadFromSourceOptions,
+    ): Promise<SourceProbe> {
+        return this.sources.probe(source, params, options);
+    }
+
+    /**
+     * Search what a source holds. Experimental.
+     * @param source - the source id or the source
+     * @param query - the search
+     * @param options - the options
+     * @returns one page of results
+     */
+    listFromSource(
+        source: string | GraphSource<never>,
+        query: SourceListQuery<Readonly<Record<string, unknown>>>,
+        options?: LoadFromSourceOptions,
+    ): Promise<SourceListing> {
+        return this.sources.search(source, query, options);
+    }
+
+    /**
+     * Tell whether data loaded from a source changed. Experimental.
+     * @param source - the source id or the source
+     * @param params - the params it was loaded with
+     * @param seen - the validators recorded then (`report.source.validators`)
+     * @param options - the options
+     * @returns whether it changed
+     */
+    validateSource(
+        source: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        seen: SourceValidators,
+        options?: LoadFromSourceOptions,
+    ): Promise<SourceFreshness> {
+        return this.sources.validate(source, params, seen, options);
+    }
+
     /**
      * Register an importer under its format name, replacing one of the same name in place (the
      * original registration order is kept).
@@ -947,7 +1107,7 @@ export class FormatRegistry {
  * @category Formats and detection
  */
 export function createRegistry(): FormatRegistry {
-    return new FormatRegistry()
+    const formats = new FormatRegistry()
         .registerImporter(jsonImporter)
         .registerExporter(jsonExporter)
         .registerImporter(graphmlImporter)
@@ -974,6 +1134,10 @@ export function createRegistry(): FormatRegistry {
         .registerExporter(oboExporter)
         .registerImporter(cysImporter)
         .registerExporter(cysExporter);
+    for (const source of builtinSources()) {
+        formats.registerSource(source);
+    }
+    return formats;
 }
 
 /**
@@ -1928,3 +2092,164 @@ function readerIterator(stream: ReadableStream<Uint8Array>, signal: AbortSignal
         },
     };
 }
+
+// ============================================================ network sources (experimental)
+
+/**
+ * Load a graph from a network source: a built-in one by id ("ndex", "neo4j", "openalex", ...),
+ * one you registered with registerSource(), or a source object. The source fetches through a
+ * guarded fetch that sends the credential only to the endpoint's origin, never over plain http
+ * (except to this machine), never across a redirect, and retries what is safe to retry. Every
+ * failure is an ImportError whose `issue.code` is one of SOURCE_ISSUE and whose `issue.params`
+ * holds its values. A capped load warns W_SOURCE_LIMIT and gives `report.source.next`, which you
+ * pass as `cursor` to continue. `result.format` is "source:<id>", or the format a file source
+ * was read as. Experimental.
+ * @param source - the source id
+ * @param params - its params, typed by SourceParamsMap
+ * @param options - endpoint, credential, cursor, caps, retries and the import options
+ * @returns the graph, the format and the report
+ * @example
+ * ```ts
+ * const { snapshot } = await loadFromSource("people", { team: "core" }, { endpoint: "https://example.com" });
+ * ```
+ * @category Network sources
+ */
+export function loadFromSource<K extends keyof SourceParamsMap>(
+    source: K,
+    params: SourceParamsMap[K],
+    options?: LoadFromSourceOptions,
+): Promise<ImportGraphResult>;
+/**
+ * Load a graph from a network source by id or as an object. Experimental.
+ * @param source - the source id or the source
+ * @param params - its params
+ * @param options - endpoint, credential, cursor, caps, retries and the import options
+ * @returns the graph, the format and the report
+ * @category Network sources
+ */
+export function loadFromSource<P>(
+    source: string | GraphSource<P>,
+    params: P,
+    options?: LoadFromSourceOptions,
+): Promise<ImportGraphResult>;
+/**
+ * The implementation of both loadFromSource() signatures.
+ * @param source - the source id or the source
+ * @param params - its params
+ * @param options - the options
+ * @returns the graph, the format and the report
+ */
+export function loadFromSource(
+    source: string | GraphSource<never>,
+    params: unknown,
+    options?: LoadFromSourceOptions,
+): Promise<ImportGraphResult> {
+    return registry.loadFromSource(source, params as Readonly<Record<string, unknown>>, options);
+}
+
+/**
+ * Load from a network source into a sink you own (a GraphBuilder you keep filling). Experimental.
+ * @param source - the source id or the source
+ * @param params - its params
+ * @param sink - where to write
+ * @param options - the options of loadFromSource()
+ * @returns the report
+ * @category Network sources
+ */
+export function importFromSource<P>(
+    source: string | GraphSource<P>,
+    params: P,
+    sink: GraphSink,
+    options?: LoadFromSourceOptions,
+): Promise<ImportReport> {
+    return registry.importFromSource(source, params as Readonly<Record<string, unknown>>, sink, options);
+}
+
+/**
+ * Fetch the neighborhood of some nodes from a source that can expand: a graph of only what was
+ * fetched (the seeds, their neighbors and the edges between them), to merge into the graph you
+ * hold. A source without `expand` rejects with E_SOURCE_UNSUPPORTED. Experimental.
+ * @param source - the source id or the source
+ * @param request - the params, seeds, depth, direction and limit
+ * @param options - the options of loadFromSource()
+ * @returns the fetched part, the format and the report
+ * @category Network sources
+ */
+export function expandFromSource<P>(
+    source: string | GraphSource<P>,
+    request: ExpandRequest<P>,
+    options?: LoadFromSourceOptions,
+): Promise<ImportGraphResult> {
+    return registry.expandFromSource(source, request as ExpandRequest<Readonly<Record<string, unknown>>>, options);
+}
+
+/**
+ * Check a source's params and credential without loading the graph. Experimental.
+ * @param source - the source id or the source
+ * @param params - its params
+ * @param options - the options of loadFromSource()
+ * @returns what the service said
+ * @category Network sources
+ */
+export function probeSource<P>(
+    source: string | GraphSource<P>,
+    params: P,
+    options?: LoadFromSourceOptions,
+): Promise<SourceProbe> {
+    return registry.probeSource(source, params as Readonly<Record<string, unknown>>, options);
+}
+
+/**
+ * Search what a source holds (NDEx networks, ...). Experimental.
+ * @param source - the source id or the source
+ * @param query - params narrowing the search, the search text, cursor and page size
+ * @param options - the options of loadFromSource()
+ * @returns one page of results
+ * @category Network sources
+ */
+export function listFromSource<P>(
+    source: string | GraphSource<P>,
+    query: SourceListQuery<P>,
+    options?: LoadFromSourceOptions,
+): Promise<SourceListing> {
+    return registry.listFromSource(source, query, options);
+}
+
+/**
+ * Tell whether data loaded from a source earlier changed. Experimental.
+ * @param source - the source id or the source
+ * @param params - the params it was loaded with
+ * @param seen - the validators recorded then (`report.source.validators`)
+ * @param options - the options of loadFromSource()
+ * @returns current, changed or unverifiable
+ * @category Network sources
+ */
+export function validateSource<P>(
+    source: string | GraphSource<P>,
+    params: P,
+    seen: SourceValidators,
+    options?: LoadFromSourceOptions,
+): Promise<SourceFreshness> {
+    return registry.validateSource(source, params as Readonly<Record<string, unknown>>, seen, options);
+}
+
+/**
+ * Register a network source in the default registry, so loadFromSource() and graphty-element
+ * find it by id. Throws an ImportError with E_SOURCE_INVALID for a malformed source or an id
+ * already taken. Experimental.
+ * @param source - the source, or a lazy source that loads its code on first use
+ * @category Network sources
+ */
+export function registerSource<P>(source: GraphSource<P> | LazySource): void {
+    registry.registerSource(source);
+}
+
+/**
+ * Every source in the default registry with its descriptor (what a form asks for), loading no
+ * source code. Experimental.
+ * @returns one entry per source: id, descriptor, whether its code is loaded
+ * @category Network sources
+ */
+export function listSources(): readonly SourceInfo[] {
+    return registry.listSources();
+}

package/src/sources/builtins.ts

@@ -0,0 +1,56 @@
+/**
+ * The built-in sources, registered as lazy sources: their descriptors are here, their code loads
+ * on first use through a dynamic import of the source's subpath.
+ */
+
+import { CYPHER_DESCRIPTOR, NEO4J_DESCRIPTOR, NEPTUNE_DESCRIPTOR } from "./cypher/descriptor.js";
+import {
+    CYPHER_SOURCE_ID,
+    NDEX_SOURCE_ID,
+    NEO4J_SOURCE_ID,
+    NEPTUNE_SOURCE_ID,
+    OPENALEX_SOURCE_ID,
+    REST_SOURCE_ID,
+} from "./ids.js";
+import { NDEX_DESCRIPTOR } from "./ndex/descriptor.js";
+import { OPENALEX_DESCRIPTOR, REST_DESCRIPTOR } from "./rest/descriptor.js";
+import { type LazySource } from "./types.js";
+
+/**
+ * The six built-in sources, each loading its subpath on first use.
+ * @returns the lazy sources, in catalog order
+ */
+export function builtinSources(): readonly LazySource[] {
+    return [
+        {
+            id: NDEX_SOURCE_ID,
+            descriptor: NDEX_DESCRIPTOR,
+            load: async () => (await import("./ndex/index.js")).ndexSource,
+        },
+        {
+            id: CYPHER_SOURCE_ID,
+            descriptor: CYPHER_DESCRIPTOR,
+            load: async () => (await import("./cypher/index.js")).cypherSource,
+        },
+        {
+            id: NEO4J_SOURCE_ID,
+            descriptor: NEO4J_DESCRIPTOR,
+            load: async () => (await import("./cypher/index.js")).neo4jSource,
+        },
+        {
+            id: NEPTUNE_SOURCE_ID,
+            descriptor: NEPTUNE_DESCRIPTOR,
+            load: async () => (await import("./cypher/index.js")).neptuneSource,
+        },
+        {
+            id: REST_SOURCE_ID,
+            descriptor: REST_DESCRIPTOR,
+            load: async () => (await import("./rest/index.js")).restMappingSource,
+        },
+        {
+            id: OPENALEX_SOURCE_ID,
+            descriptor: OPENALEX_DESCRIPTOR,
+            load: async () => (await import("./rest/index.js")).openalexSource,
+        },
+    ];
+}

package/src/sources/codes.ts

@@ -0,0 +1,235 @@
+/**
+ * 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",
+} as const);
+
+/**
+ * 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 & {}); // NOSONAR(S4335): open string union, keeps the known names autocompleting
+
+/**
+ * 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;
+    };
+}