@graphty/graph-io 0.3.47 → 0.3.48

package/dist/src/sources/ndex/index.js

@@ -0,0 +1,191 @@
+/**
+ * `@graphty/graph-io/sources/ndex`: the NDEx source (design section 12.1). Experimental.
+ *
+ * - load: the network's summary first (counts, download size, modification time), checked against
+ *   the caps before a byte of the network is read; then the CX2 (or CX) download, streamed into
+ *   the CX2 (or CX) importer.
+ * - probe: the summary. list: NDEx's v2 network search. validate: the summary's modificationTime.
+ * - expand: NDEx's neighborhood query (`expand.ts`).
+ *
+ * Errors are classified by status; a body is read only from a 401, 403 or 404 (NDEx's own
+ * `errorCode`, passed through as `serverCode`), so a 500 with a Java stack trace never reaches a
+ * report.
+ * @module @graphty/graph-io/sources/ndex
+ */
+import { defineSource } from "../define.js";
+import { failOn } from "../fail.js";
+import { NDEX_SOURCE_ID } from "../ids.js";
+import { checkedUuid, checkEndpoint, ndexFetch } from "./client.js";
+import { NDEX_DESCRIPTOR } from "./descriptor.js";
+import { expandNdex } from "./expand.js";
+export { NDEX_DESCRIPTOR } from "./descriptor.js";
+export { parseShareUrl } from "./share-url.js";
+/**
+ * Read a network's summary.
+ * @param uuid - the checked UUID
+ * @param ctx - the context
+ * @returns the summary and the bytes it took
+ */
+async function readSummary(uuid, ctx) {
+    const response = await ndexFetch(ctx, `v3/networks/${uuid}/summary`, uuid, {
+        headers: { Accept: "application/json" },
+    });
+    const text = await response.text();
+    try {
+        return { summary: JSON.parse(text), bytes: new TextEncoder().encode(text).byteLength };
+    }
+    catch {
+        return failOn(ctx.report, "E_SOURCE_RESPONSE", "the NDEx summary is not JSON", {
+            expected: "json",
+            contentType: response.headers.get("content-type"),
+        });
+    }
+}
+/**
+ * An NDEx time (epoch milliseconds) as an ISO string.
+ * @param ms - the time
+ * @returns the ISO string, or undefined
+ */
+function iso(ms) {
+    return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+}
+/**
+ * The download size the summary gives for a format.
+ * @param summary - the summary
+ * @param format - "cx2" or "cx"
+ * @returns the size in bytes, or undefined
+ */
+function sizeOf(summary, format) {
+    return format === "cx" ? summary.cxFileSize : summary.cx2FileSize;
+}
+/**
+ * Stop the load before its first byte when the summary says a cap would cut it: a network file cut
+ * short is not a graph, so this is E_SOURCE_LIMIT under either `onLimit`.
+ * @param summary - the summary
+ * @param format - the download format
+ * @param ctx - the context
+ */
+function checkCaps(summary, format, ctx) {
+    const caps = [
+        ["maxNodes", summary.nodeCount, ctx.limits.maxNodes],
+        ["maxEdges", summary.edgeCount, ctx.limits.maxEdges],
+        ["maxBytes", sizeOf(summary, format), ctx.limits.maxBytes],
+    ];
+    for (const [limit, value, cap] of caps) {
+        if (value !== undefined && cap !== undefined && value > cap) {
+            failOn(ctx.report, "E_SOURCE_LIMIT", `the network's ${limit} of ${String(value)} is over the cap`, {
+                limit,
+                value,
+            });
+        }
+    }
+}
+/**
+ * The graph facts a summary adds: when it changed, and who may use it.
+ * @param summary - the summary
+ * @returns the facts
+ */
+function metaOf(summary) {
+    const meta = {};
+    const modified = iso(summary.modificationTime);
+    if (modified !== undefined) {
+        meta.modified = modified;
+    }
+    if (typeof summary.visibility === "string") {
+        meta.visibility = summary.visibility;
+    }
+    for (const key of ["rights", "rightsHolder"]) {
+        const value = summary.properties?.[key]?.v;
+        if (typeof value === "string") {
+            meta[key] = value;
+        }
+    }
+    return meta;
+}
+/**
+ * The validators of a summary.
+ * @param summary - the summary
+ * @returns `{ modified }` when NDEx gave a modification time
+ */
+function validatorsOf(summary) {
+    const modified = iso(summary.modificationTime);
+    return modified === undefined ? {} : { modified };
+}
+/**
+ * The NDEx source. Experimental.
+ * @category Network sources
+ */
+export const ndexSource = defineSource({
+    id: NDEX_SOURCE_ID,
+    descriptor: NDEX_DESCRIPTOR,
+    async file(params, ctx) {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const format = params.format ?? "cx2";
+        const { summary, bytes } = await readSummary(uuid, ctx);
+        checkCaps(summary, format, ctx);
+        const size = sizeOf(summary, format);
+        // progress counts every byte read, the summary's included
+        ctx.progress(bytes, size === undefined ? undefined : bytes + size, "bytes");
+        // records the validators in report.source; the file path keeps them
+        ctx.finish({ validators: validatorsOf(summary) });
+        const path = format === "cx" ? `v2/network/${uuid}` : `v3/networks/${uuid}`;
+        const body = await ndexFetch(ctx, path, uuid);
+        return { body, format, meta: metaOf(summary) };
+    },
+    async probe(params, ctx) {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const { summary } = await readSummary(uuid, ctx);
+        return {
+            ok: true,
+            counts: {
+                nodes: summary.nodeCount,
+                edges: summary.edgeCount,
+                bytes: sizeOf(summary, params.format ?? "cx2"),
+            },
+        };
+    },
+    async list(query, ctx) {
+        checkEndpoint(ctx);
+        const start = Number(query.cursor?.start ?? 0);
+        const size = query.size ?? 25;
+        const body = await ctx.fetchJson(`v2/search/network?start=${String(start)}&size=${String(size)}`, {
+            method: "POST",
+            idempotent: true,
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ searchString: query.search ?? "" }),
+        });
+        const networks = Array.isArray(body.networks)
+            ? body.networks
+            : failOn(ctx.report, "E_SOURCE_RESPONSE", "the NDEx search answer has no networks", {
+                expected: "ndex-search",
+                contentType: "application/json",
+            });
+        const { numFound } = body;
+        const items = networks.flatMap((n) => typeof n.externalId === "string"
+            ? [
+                {
+                    params: { uuid: n.externalId },
+                    name: n.name ?? n.externalId,
+                    nodeCount: n.nodeCount,
+                    edgeCount: n.edgeCount,
+                    modified: iso(n.modificationTime),
+                },
+            ]
+            : []);
+        const total = typeof numFound === "number" ? numFound : undefined;
+        const more = total === undefined ? networks.length === size : start + networks.length < total;
+        return { items, next: more && networks.length > 0 ? { start: start + networks.length } : null, total };
+    },
+    async validate(params, seen, ctx) {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const validators = validatorsOf((await readSummary(uuid, ctx)).summary);
+        if (seen.modified === undefined || validators.modified === undefined) {
+            return { status: "unverifiable", validators };
+        }
+        return seen.modified === validators.modified
+            ? { status: "current", via: "modified", validators }
+            : { status: "changed", via: "modified", changedAt: validators.modified, validators };
+    },
+    expand: expandNdex,
+});
+//# sourceMappingURL=index.js.map

package/dist/src/sources/ndex/index.js.map

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

package/dist/src/sources/ndex/params.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The parameters of the NDEx source (design section 12.1). Experimental. The NDEx work may add
+ * optional fields only.
+ */
+/**
+ * What to load from NDEx. Experimental.
+ * @category Network sources
+ */
+export interface NdexParams {
+    /** The network's UUID ("86719f5b-1439-11f0-9806-005056ae3c32"). */
+    readonly uuid: string;
+    /** The download format. @defaultValue "cx2" */
+    readonly format?: "cx2" | "cx" | undefined;
+    /** The node attribute that identifies a node across NDEx's two id spaces (for expand): "name", "represents". */
+    readonly idAttribute?: string | undefined;
+}
+//# sourceMappingURL=params.d.ts.map

package/dist/src/sources/ndex/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../../src/sources/ndex/params.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,gHAAgH;IAChH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C"}

package/dist/src/sources/ndex/params.js

@@ -0,0 +1,6 @@
+/**
+ * The parameters of the NDEx source (design section 12.1). Experimental. The NDEx work may add
+ * optional fields only.
+ */
+export {};
+//# sourceMappingURL=params.js.map

package/dist/src/sources/ndex/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../../src/sources/ndex/params.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/sources/ndex/share-url.d.ts

@@ -0,0 +1,40 @@
+/**
+ * NDEx share links: a network's page or API URL, possibly carrying a link-share access key.
+ */
+import { type Credential } from "../types.js";
+/**
+ * What a share link says: the network, the NDEx server, and the access key as a credential.
+ * Experimental.
+ * @category Network sources
+ */
+export interface NdexShareLink {
+    /** The params to load the network with. */
+    readonly params: {
+        /** The network's NDEx id. */
+        readonly uuid: string;
+    };
+    /** The NDEx server the link points at ("https://www.ndexbio.org/"). */
+    readonly endpoint: string;
+    /** The link's access key, sent only to that server; absent when the link has none. */
+    readonly credential?: Credential | undefined;
+}
+/**
+ * Read an NDEx share link (`https://www.ndexbio.org/viewer/networks/<uuid>?accesskey=<key>`, the
+ * older `#/network/<uuid>` form, or an API URL). The access key leaves the URL and becomes a
+ * credential bound to the link's server, so it is never logged or stored with the params.
+ * Rejects with `E_SOURCE_PARAM` (`name: "url"`): `reason: "format"` when the text is not a URL
+ * naming a network, `"credentials-in-url"` when it carries a user name or password. Experimental.
+ * @param url - the link
+ * @returns the params, endpoint and credential to load it with
+ * @example
+ * ```ts
+ * const link = parseShareUrl(sharedUrl);
+ * const { snapshot } = await loadFromSource("ndex", link.params, {
+ *     endpoint: link.endpoint,
+ *     credential: link.credential,
+ * });
+ * ```
+ * @category Network sources
+ */
+export declare function parseShareUrl(url: string | URL): NdexShareLink;
+//# sourceMappingURL=share-url.d.ts.map

package/dist/src/sources/ndex/share-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-url.d.ts","sourceRoot":"","sources":["../../../../src/sources/ndex/share-url.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAM9C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE;QACb,6BAA6B;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,aAAa,CA0B9D"}

package/dist/src/sources/ndex/share-url.js

@@ -0,0 +1,64 @@
+/**
+ * NDEx share links: a network's page or API URL, possibly carrying a link-share access key.
+ */
+import { credentials } from "../credentials.js";
+import { failAlone } from "../fail.js";
+import { NDEX_SOURCE_ID } from "../ids.js";
+import { ACCESS_KEY_QUERY } from "./client.js";
+/** A network UUID anywhere in a URL's path or hash. */
+const UUID_IN_URL = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/**
+ * Read an NDEx share link (`https://www.ndexbio.org/viewer/networks/<uuid>?accesskey=<key>`, the
+ * older `#/network/<uuid>` form, or an API URL). The access key leaves the URL and becomes a
+ * credential bound to the link's server, so it is never logged or stored with the params.
+ * Rejects with `E_SOURCE_PARAM` (`name: "url"`): `reason: "format"` when the text is not a URL
+ * naming a network, `"credentials-in-url"` when it carries a user name or password. Experimental.
+ * @param url - the link
+ * @returns the params, endpoint and credential to load it with
+ * @example
+ * ```ts
+ * const link = parseShareUrl(sharedUrl);
+ * const { snapshot } = await loadFromSource("ndex", link.params, {
+ *     endpoint: link.endpoint,
+ *     credential: link.credential,
+ * });
+ * ```
+ * @category Network sources
+ */
+export function parseShareUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return refuse("format");
+    }
+    if (parsed.username !== "" || parsed.password !== "") {
+        return refuse("credentials-in-url");
+    }
+    // the older viewer keeps the network and its key in the hash
+    const hash = new URL(parsed.hash.replace(/^#/, ""), "https://hash.invalid/");
+    const uuid = UUID_IN_URL.exec(`${parsed.pathname} ${hash.pathname}`)?.[0];
+    if (uuid === undefined || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+        return refuse("format");
+    }
+    // the bare host redirects to www without CORS headers, so a page cannot follow it
+    const host = parsed.host.toLowerCase() === "ndexbio.org" ? "www.ndexbio.org" : parsed.host;
+    const endpoint = `${parsed.protocol}//${host}/`;
+    const key = parsed.searchParams.get(ACCESS_KEY_QUERY) ?? hash.searchParams.get(ACCESS_KEY_QUERY);
+    const params = { uuid: uuid.toLowerCase() };
+    if (key === null || key === "") {
+        return { params, endpoint };
+    }
+    const credential = credentials.apiKey({ query: ACCESS_KEY_QUERY }, key, { origins: [new URL(endpoint).origin] });
+    return { params, endpoint, credential };
+}
+/**
+ * Reject a share link.
+ * @param reason - why
+ * @returns never
+ */
+function refuse(reason) {
+    return failAlone("E_SOURCE_PARAM", "not an NDEx share link", { name: "url", reason }, `source:${NDEX_SOURCE_ID}`);
+}
+//# sourceMappingURL=share-url.js.map

package/dist/src/sources/ndex/share-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-url.js","sourceRoot":"","sources":["../../../../src/sources/ndex/share-url.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,uDAAuD;AACvD,MAAM,WAAW,GAAG,+DAA+D,CAAC;AAmBpF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,GAAiB;IAC3C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QACnD,OAAO,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACxC,CAAC;IACD,6DAA6D;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,uBAAuB,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1E,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,EAAE,CAAC;QACtF,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IACD,kFAAkF;IAClF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,aAAa,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;IAC3F,MAAM,QAAQ,GAAG,GAAG,MAAM,CAAC,QAAQ,KAAK,IAAI,GAAG,CAAC;IAChD,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACjG,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;IAC5C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAChC,CAAC;IACD,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACjH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,MAAuC;IACnD,OAAO,SAAS,CAAC,gBAAgB,EAAE,wBAAwB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,cAAc,EAAE,CAAC,CAAC;AACtH,CAAC"}

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

@@ -0,0 +1,28 @@
+/**
+ * `SourceParamsMap`: the params type of every built-in source by id, so `loadFromSource("ndex", ...)`
+ * type-checks its params. A consumer adds its own source by declaration merging.
+ */
+import { type CypherParams } from "./cypher/params.js";
+import { type NdexParams } from "./ndex/params.js";
+import { type OpenAlexParams, type RestParams } from "./rest/params.js";
+/**
+ * Parameter types by source id; extend it by declaration merging:
+ * `declare module "@graphty/graph-io" { interface SourceParamsMap { people: { team: string } } }`.
+ * Experimental.
+ * @category Network sources
+ */
+export interface SourceParamsMap {
+    /** NDEx. */
+    ndex: NdexParams;
+    /** Any openCypher server. */
+    cypher: CypherParams;
+    /** Neo4j. */
+    neo4j: CypherParams;
+    /** Amazon Neptune. */
+    neptune: CypherParams;
+    /** A REST API through a mapping. */
+    rest: RestParams;
+    /** OpenAlex. */
+    openalex: OpenAlexParams;
+}
+//# sourceMappingURL=params.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../src/sources/params.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,YAAY;IACZ,IAAI,EAAE,UAAU,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa;IACb,KAAK,EAAE,YAAY,CAAC;IACpB,sBAAsB;IACtB,OAAO,EAAE,YAAY,CAAC;IACtB,oCAAoC;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,gBAAgB;IAChB,QAAQ,EAAE,cAAc,CAAC;CAC5B"}

package/dist/src/sources/params.js

@@ -0,0 +1,6 @@
+/**
+ * `SourceParamsMap`: the params type of every built-in source by id, so `loadFromSource("ndex", ...)`
+ * type-checks its params. A consumer adds its own source by declaration merging.
+ */
+export {};
+//# sourceMappingURL=params.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../src/sources/params.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -0,0 +1,118 @@
+/**
+ * The source registry (design section 3): sources by id, in their own name space beside the
+ * formats. Lazy sources are registered by descriptor and load their code on first use, so listing
+ * sources loads none. A FormatRegistry holds one, so one object holds formats and sources.
+ */
+import { type GraphBuilder, type GraphSink } from "@graphty/graph-format";
+import { type FormatRegistry, type ImportGraphResult } from "../registry.js";
+import { type ImportReport } from "../types.js";
+import { type ExpandRequest, type GraphSource, type LazySource, type LoadFromSourceOptions, type SourceFreshness, type SourceInfo, type SourceListing, type SourceListQuery, type SourceProbe, type SourceValidators } from "./types.js";
+/** What a SourceRegistry borrows from its FormatRegistry: building and freezing a graph. */
+interface SourceBuilding {
+    /**
+     * A builder seeded from the load options.
+     * @param options - the options
+     * @param format - the report format name
+     * @returns the builder
+     */
+    readonly newBuilder: (options: LoadFromSourceOptions, format: string) => GraphBuilder;
+    /**
+     * Freeze a filled builder into a load result.
+     * @param format - the result's format
+     * @param builder - the builder
+     * @param report - the report
+     * @param options - the options
+     * @returns the result
+     */
+    readonly freeze: (format: string, builder: GraphBuilder, report: ImportReport, options: LoadFromSourceOptions) => ImportGraphResult;
+}
+/**
+ * The sources of one FormatRegistry. Experimental.
+ * @category Network sources
+ */
+export declare class SourceRegistry {
+    private readonly formats;
+    private readonly building;
+    private readonly entries;
+    /**
+     * Create one for a format registry, whose importers read `file` sources.
+     * @param formats - the format registry
+     * @param building - how it builds and freezes graphs
+     */
+    constructor(formats: FormatRegistry, building: SourceBuilding);
+    /**
+     * Register a source or a lazy source. A malformed one, or an id already taken, throws an
+     * ImportError with E_SOURCE_INVALID.
+     * @param source - the source
+     */
+    register(source: GraphSource<never> | LazySource): void;
+    /**
+     * Whether a source id is registered.
+     * @param id - the id
+     * @returns true when registered
+     */
+    has(id: string): boolean;
+    /**
+     * Every registered source, without loading any code.
+     * @returns one entry per source, in registration order
+     */
+    list(): readonly SourceInfo[];
+    /**
+     * A source by id, loading a lazy one; a source object passes through after its checks.
+     * @param source - the id or the source
+     * @returns the loaded source
+     */
+    resolve(source: string | GraphSource<never>): Promise<GraphSource<never>>;
+    /**
+     * Load a graph from a source.
+     * @param source - the id or the source
+     * @param params - its params
+     * @param options - endpoint, credential, cursor, caps and the import options
+     * @returns the graph and the report
+     */
+    load(source: string | GraphSource<never>, params: Readonly<Record<string, unknown>>, options?: LoadFromSourceOptions): Promise<ImportGraphResult>;
+    /**
+     * Load from a source into a sink you own.
+     * @param source - the id or the source
+     * @param params - its params
+     * @param sink - where to write
+     * @param options - the options
+     * @returns the report
+     */
+    import(source: string | GraphSource<never>, params: Readonly<Record<string, unknown>>, sink: GraphSink, options?: LoadFromSourceOptions): Promise<ImportReport>;
+    /**
+     * Fetch the neighborhood of some nodes: a snapshot of only what was fetched.
+     * @param source - the id or the source
+     * @param request - the seeds and how far to go
+     * @param options - the options
+     * @returns the fetched part and the report
+     */
+    expand(source: string | GraphSource<never>, request: ExpandRequest<Readonly<Record<string, unknown>>>, options?: LoadFromSourceOptions): Promise<ImportGraphResult>;
+    /**
+     * Check params and credential without loading.
+     * @param source - the id or the source
+     * @param params - its params
+     * @param options - the options
+     * @returns what the service said
+     */
+    probe(source: string | GraphSource<never>, params: Readonly<Record<string, unknown>>, options?: LoadFromSourceOptions): Promise<SourceProbe>;
+    /**
+     * Search what a source holds.
+     * @param source - the id or the source
+     * @param query - the search
+     * @param options - the options
+     * @returns one page of results
+     */
+    search(source: string | GraphSource<never>, query: SourceListQuery<Readonly<Record<string, unknown>>>, options?: LoadFromSourceOptions): Promise<SourceListing>;
+    /**
+     * Tell whether data loaded earlier changed.
+     * @param source - the id or the source
+     * @param params - the params it was loaded with
+     * @param seen - the validators recorded then
+     * @param options - the options
+     * @returns whether it changed
+     */
+    validate(source: string | GraphSource<never>, params: Readonly<Record<string, unknown>>, seen: SourceValidators, options?: LoadFromSourceOptions): Promise<SourceFreshness>;
+}
+export {};
+//# sourceMappingURL=registry.d.ts.map

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

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