@graphty/graph-io 0.3.47 → 0.3.48

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

@@ -0,0 +1,64 @@
+/**
+ * The public names of network sources: one constant per built-in source id, and the reserved
+ * `_source.` attribute names. Nothing else in graph-io spells them, so a rename is one edit here.
+ *
+ * Experimental: the ids and the `_source.` namespace await the owner's final word (design
+ * section 22, items 4 and 5).
+ */
+/**
+ * The NDEx source (www.ndexbio.org). Experimental.
+ * @category Network sources
+ */
+export declare const NDEX_SOURCE_ID = "ndex";
+/**
+ * The generic Cypher source, for any openCypher server. Experimental.
+ * @category Network sources
+ */
+export declare const CYPHER_SOURCE_ID = "cypher";
+/**
+ * The Neo4j preset of the Cypher source. Experimental.
+ * @category Network sources
+ */
+export declare const NEO4J_SOURCE_ID = "neo4j";
+/**
+ * The Amazon Neptune preset of the Cypher source. Experimental.
+ * @category Network sources
+ */
+export declare const NEPTUNE_SOURCE_ID = "neptune";
+/**
+ * The generic REST mapping source. Experimental.
+ * @category Network sources
+ */
+export declare const REST_SOURCE_ID = "rest";
+/**
+ * The OpenAlex preset of the REST mapping source. Experimental.
+ * @category Network sources
+ */
+export declare const OPENALEX_SOURCE_ID = "openalex";
+/**
+ * The prefix of the reserved attribute namespace sources and graphty-element write facts under.
+ * @category Network sources
+ */
+export declare const SOURCE_ATTR_PREFIX = "_source.";
+/**
+ * Node attribute: true on a stub, a node known only by its id until it is hydrated or expanded.
+ * @category Network sources
+ */
+export declare const SOURCE_STUB_ATTR = "_source.stub";
+/**
+ * Node attribute: the entity a stub node is (a REST mapping's entity name).
+ * @category Network sources
+ */
+export declare const SOURCE_ENTITY_ATTR = "_source.entity";
+/**
+ * Node attribute: the node's degree at the source, when the source returns it at no extra cost
+ * (the Cypher source's degree hint).
+ * @category Network sources
+ */
+export declare const SOURCE_DEGREE_ATTR = "_source.degree";
+/**
+ * The prefix of `ImportGraphResult.format` for a load from a source: `"source:<id>"`.
+ * @category Network sources
+ */
+export declare const SOURCE_FORMAT_PREFIX = "source:";
+//# sourceMappingURL=ids.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/sources/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,YAAY,CAAC"}

package/dist/src/sources/ids.js

@@ -0,0 +1,64 @@
+/**
+ * The public names of network sources: one constant per built-in source id, and the reserved
+ * `_source.` attribute names. Nothing else in graph-io spells them, so a rename is one edit here.
+ *
+ * Experimental: the ids and the `_source.` namespace await the owner's final word (design
+ * section 22, items 4 and 5).
+ */
+/**
+ * The NDEx source (www.ndexbio.org). Experimental.
+ * @category Network sources
+ */
+export const NDEX_SOURCE_ID = "ndex";
+/**
+ * The generic Cypher source, for any openCypher server. Experimental.
+ * @category Network sources
+ */
+export const CYPHER_SOURCE_ID = "cypher";
+/**
+ * The Neo4j preset of the Cypher source. Experimental.
+ * @category Network sources
+ */
+export const NEO4J_SOURCE_ID = "neo4j";
+/**
+ * The Amazon Neptune preset of the Cypher source. Experimental.
+ * @category Network sources
+ */
+export const NEPTUNE_SOURCE_ID = "neptune";
+/**
+ * The generic REST mapping source. Experimental.
+ * @category Network sources
+ */
+export const REST_SOURCE_ID = "rest";
+/**
+ * The OpenAlex preset of the REST mapping source. Experimental.
+ * @category Network sources
+ */
+export const OPENALEX_SOURCE_ID = "openalex";
+/**
+ * The prefix of the reserved attribute namespace sources and graphty-element write facts under.
+ * @category Network sources
+ */
+export const SOURCE_ATTR_PREFIX = "_source.";
+/**
+ * Node attribute: true on a stub, a node known only by its id until it is hydrated or expanded.
+ * @category Network sources
+ */
+export const SOURCE_STUB_ATTR = "_source.stub";
+/**
+ * Node attribute: the entity a stub node is (a REST mapping's entity name).
+ * @category Network sources
+ */
+export const SOURCE_ENTITY_ATTR = "_source.entity";
+/**
+ * Node attribute: the node's degree at the source, when the source returns it at no extra cost
+ * (the Cypher source's degree hint).
+ * @category Network sources
+ */
+export const SOURCE_DEGREE_ATTR = "_source.degree";
+/**
+ * The prefix of `ImportGraphResult.format` for a load from a source: `"source:<id>"`.
+ * @category Network sources
+ */
+export const SOURCE_FORMAT_PREFIX = "source:";
+//# sourceMappingURL=ids.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/sources/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * What every NDEx call shares: the checks on the endpoint and the network UUID, and a fetch that
+ * classifies NDEx's failures.
+ */
+import { type SourceContext } from "../types.js";
+/** The query parameter NDEx reads a link-share access key from. */
+export declare const ACCESS_KEY_QUERY = "accesskey";
+/**
+ * Refuse an access key in the endpoint: it belongs in a credential, which is never logged.
+ * @param ctx - the context
+ */
+export declare function checkEndpoint(ctx: SourceContext): void;
+/**
+ * Check a call's endpoint and network UUID.
+ * @param uuid - the network UUID
+ * @param ctx - the context
+ * @returns the UUID, lowercase and URL-safe
+ */
+export declare function checkedUuid(uuid: unknown, ctx: SourceContext): string;
+/**
+ * Fetch from NDEx, turning a 401, 403 or 404 into its coded error with NDEx's own errorCode.
+ * @param ctx - the context
+ * @param path - the path, relative to the endpoint
+ * @param uuid - the network the request is about, for E_SOURCE_NOT_FOUND
+ * @param init - the request init
+ * @returns the response, status 2xx
+ */
+export declare function ndexFetch(ctx: SourceContext, path: string, uuid: string | null, init?: RequestInit & {
+    readonly idempotent?: boolean;
+}): Promise<Response>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/sources/ndex/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAK5C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAOtD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CAarE;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC3B,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,IAAI,GAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,OAAO,CAAC,QAAQ,CAAC,CAuBnB"}

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

@@ -0,0 +1,90 @@
+/**
+ * What every NDEx call shares: the checks on the endpoint and the network UUID, and a fetch that
+ * classifies NDEx's failures.
+ */
+import { failOn } from "../fail.js";
+/** An NDEx network UUID. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The query parameter NDEx reads a link-share access key from. */
+export const ACCESS_KEY_QUERY = "accesskey";
+/** The statuses whose JSON body (NDEx's errorCode) is read; every other failure is classified by status alone. */
+const READ_STATUSES = [401, 403, 404];
+/**
+ * Refuse an access key in the endpoint: it belongs in a credential, which is never logged.
+ * @param ctx - the context
+ */
+export function checkEndpoint(ctx) {
+    if (ctx.endpoint?.searchParams.has(ACCESS_KEY_QUERY) === true) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "an access key goes in a credential, never in the endpoint", {
+            name: "endpoint",
+            reason: "credentials-in-url",
+        });
+    }
+}
+/**
+ * Check a call's endpoint and network UUID.
+ * @param uuid - the network UUID
+ * @param ctx - the context
+ * @returns the UUID, lowercase and URL-safe
+ */
+export function checkedUuid(uuid, ctx) {
+    checkEndpoint(ctx);
+    const value = String(uuid);
+    if (/accesskey/i.test(value)) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "an access key goes in a credential, never in the uuid", {
+            name: "uuid",
+            reason: "credentials-in-url",
+        });
+    }
+    if (!UUID.test(value)) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "the uuid is not a network UUID", { name: "uuid", reason: "format" });
+    }
+    return value.toLowerCase();
+}
+/**
+ * Fetch from NDEx, turning a 401, 403 or 404 into its coded error with NDEx's own errorCode.
+ * @param ctx - the context
+ * @param path - the path, relative to the endpoint
+ * @param uuid - the network the request is about, for E_SOURCE_NOT_FOUND
+ * @param init - the request init
+ * @returns the response, status 2xx
+ */
+export async function ndexFetch(ctx, path, uuid, init = {}) {
+    const response = await ctx.fetch(path, { ...init, allowStatus: READ_STATUSES });
+    if (response.ok) {
+        return response;
+    }
+    const url = new URL(path, ctx.endpoint ?? undefined);
+    const serverCode = await errorCode(response);
+    const { status } = response;
+    if (status === 401) {
+        failOn(ctx.report, "E_SOURCE_AUTH", `NDEx answered ${String(status)}`, {
+            origin: url.origin,
+            status,
+            scheme: response.headers.get("www-authenticate")?.split(/\s/)[0] ?? null,
+            serverCode,
+        });
+    }
+    if (status === 403) {
+        failOn(ctx.report, "E_SOURCE_FORBIDDEN", "NDEx answered 403", { status, serverCode });
+    }
+    return failOn(ctx.report, "E_SOURCE_NOT_FOUND", "NDEx has no such network", {
+        what: uuid === null ? "url" : "network",
+        value: uuid ?? `${url.origin}${url.pathname}`,
+    });
+}
+/**
+ * NDEx's own error code from a JSON error body, never its message or stack trace.
+ * @param response - the failed response
+ * @returns the code, or null
+ */
+async function errorCode(response) {
+    try {
+        const body = (await response.json());
+        return typeof body.errorCode === "string" ? body.errorCode.slice(0, 100) : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=client.js.map

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * The NDEx source's descriptor: catalog data, available without loading the source's code.
+ */
+import { type SourceDescriptor } from "../types.js";
+/**
+ * The descriptor of the `ndex` source. Experimental.
+ * @category Network sources
+ */
+export declare const NDEX_DESCRIPTOR: SourceDescriptor;
+//# sourceMappingURL=descriptor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../../src/sources/ndex/descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAevE;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,gBAwC5B,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * The NDEx source's descriptor: catalog data, available without loading the source's code.
+ */
+/**
+ * One public NDEx network offered as a sample.
+ * @param id - the sample id
+ * @param plainName - its name
+ * @param uuid - the network UUID
+ * @param nodes - its node count
+ * @param edges - its edge count
+ * @returns the sample
+ */
+function sample(id, plainName, uuid, nodes, edges) {
+    return { id, plainName, params: { uuid }, counts: { nodes, edges } };
+}
+/**
+ * The descriptor of the `ndex` source. Experimental.
+ * @category Network sources
+ */
+export const NDEX_DESCRIPTOR = Object.freeze({
+    plainName: "NDEx",
+    kind: "repository",
+    version: 1,
+    defaultEndpoint: "https://www.ndexbio.org/",
+    auth: ["basic", "bearer", "api-key"],
+    authRequired: "optional",
+    rateLimit: { requests: 50, perMs: 1000, concurrent: 4 },
+    params: [
+        { name: "uuid", plainName: "Network UUID", type: "string", required: true },
+        {
+            name: "format",
+            plainName: "Format",
+            type: "enum",
+            default: "cx2",
+            advanced: true,
+            values: [
+                { value: "cx2", label: "CX2" },
+                { value: "cx", label: "CX" },
+            ],
+        },
+        { name: "idAttribute", plainName: "Id attribute", type: "string", advanced: true },
+    ],
+    features: ["probe", "list", "expand", "validate"],
+    samples: [
+        sample("ndex-wp5483", "WikiPathways WP5483", "86719f5b-1439-11f0-9806-005056ae3c32", 57, 34),
+        sample("ndex-nci-pid", "NCI PID cancer signaling", "640e2cef-795d-11e8-a4bf-0ac135e8bacf", 2794, 25296),
+        sample("ndex-huri", "HuRI human interactome", "73bc2c06-5fb2-11e9-9f06-0ac135e8bacf", 8275, 52569),
+        sample("ndex-signor", "Signor", "523fff27-afe8-11e9-8bb4-0ac135e8bacf", 10339, 33381),
+        sample("ndex-dgidb", "DGIdb drugs and target genes", "7e5e64ff-f6cf-11ea-99da-0ac135e8bacf", 12100, 32814),
+        sample("ndex-wikipathways-landscape", "WikiPathways landscape", "2b3ed6af-5031-11eb-9e72-0ac135e8bacf", 32077, 74109),
+        // 3.3 million edges and a 690 MB download: offered for neighborhoods, and as a maxBytes test
+        { ...sample("ndex-pcnet", "PCNet 2.2", "8b4b54fa-e87d-11ee-9621-005056ae23aa", 18558, 3323928), whole: false },
+    ],
+});
+//# sourceMappingURL=descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../../../../src/sources/ndex/descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;GAQG;AACH,SAAS,MAAM,CAAC,EAAU,EAAE,SAAiB,EAAE,IAAY,EAAE,KAAa,EAAE,KAAa;IACrF,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC3D,SAAS,EAAE,MAAM;IACjB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,CAAC;IACV,eAAe,EAAE,0BAA0B;IAC3C,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC;IACpC,YAAY,EAAE,UAAU;IACxB,SAAS,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE;IACvD,MAAM,EAAE;QACJ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC3E;YACI,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,QAAQ;YACnB,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE;gBACJ,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;gBAC9B,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;aAC/B;SACJ;QACD,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;KACrF;IACD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC;IACjD,OAAO,EAAE;QACL,MAAM,CAAC,aAAa,EAAE,qBAAqB,EAAE,sCAAsC,EAAE,EAAE,EAAE,EAAE,CAAC;QAC5F,MAAM,CAAC,cAAc,EAAE,0BAA0B,EAAE,sCAAsC,EAAE,IAAI,EAAE,KAAK,CAAC;QACvG,MAAM,CAAC,WAAW,EAAE,wBAAwB,EAAE,sCAAsC,EAAE,IAAI,EAAE,KAAK,CAAC;QAClG,MAAM,CAAC,aAAa,EAAE,QAAQ,EAAE,sCAAsC,EAAE,KAAK,EAAE,KAAK,CAAC;QACrF,MAAM,CAAC,YAAY,EAAE,8BAA8B,EAAE,sCAAsC,EAAE,KAAK,EAAE,KAAK,CAAC;QAC1G,MAAM,CACF,6BAA6B,EAC7B,wBAAwB,EACxB,sCAAsC,EACtC,KAAK,EACL,KAAK,CACR;QACD,6FAA6F;QAC7F,EAAE,GAAG,MAAM,CAAC,YAAY,EAAE,WAAW,EAAE,sCAAsC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE;KACjH;CACJ,CAAC,CAAC"}

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

@@ -0,0 +1,20 @@
+/**
+ * The NDEx source's expand: NDEx's neighborhood query (`POST /v2/search/network/{uuid}/query`),
+ * which answers CX1, read by the CX importer. Seeds are node ids, sent as `nodeIds`; NDEx's CX1
+ * answer keeps the ids of the CX2 download (checked on 2026-10-17), so an expansion merges into a
+ * loaded network by id. With `idAttribute`, seeds are values of that node attribute instead,
+ * matched by NDEx's node search.
+ */
+import { type GraphSink } from "@graphty/graph-format";
+import { type ImportReport } from "../../types.js";
+import { type ExpandRequest, type SourceContext } from "../types.js";
+import { type NdexParams } from "./params.js";
+/**
+ * Fetch the neighborhood of some nodes of an NDEx network into a sink.
+ * @param request - the seeds, depth and limit; `limit` caps the edges NDEx returns
+ * @param sink - where to write
+ * @param ctx - the context
+ * @returns the report
+ */
+export declare function expandNdex(request: ExpandRequest<NdexParams>, sink: GraphSink, ctx: SourceContext): Promise<ImportReport>;
+//# sourceMappingURL=expand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../../../../src/sources/ndex/expand.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAErE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAoD9C;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC5B,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,EAClC,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,aAAa,GACnB,OAAO,CAAC,YAAY,CAAC,CAqBvB"}

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

@@ -0,0 +1,87 @@
+/**
+ * The NDEx source's expand: NDEx's neighborhood query (`POST /v2/search/network/{uuid}/query`),
+ * which answers CX1, read by the CX importer. Seeds are node ids, sent as `nodeIds`; NDEx's CX1
+ * answer keeps the ids of the CX2 download (checked on 2026-10-17), so an expansion merges into a
+ * loaded network by id. With `idAttribute`, seeds are values of that node attribute instead,
+ * matched by NDEx's node search.
+ */
+import { cxImporter } from "../../formats/cx/importer.js";
+import { failOn } from "../fail.js";
+import { checkedUuid, ndexFetch } from "./client.js";
+/** The deepest neighborhood asked for, as for every built-in source. */
+const MAX_DEPTH = 10;
+/**
+ * Quote a value for NDEx's search syntax.
+ * @param value - the value
+ * @returns the quoted term
+ */
+function term(value) {
+    const escaped = value.replaceAll(/["\\]/g, String.raw `\$&`);
+    return `"${escaped}"`;
+}
+/**
+ * The query body: the seeds as node ids, or as values of `idAttribute`.
+ * @param request - the expand request
+ * @param ctx - the context
+ * @returns the body NDEx's query takes
+ */
+function queryBody(request, ctx) {
+    const { ids } = request;
+    const { idAttribute } = request.params;
+    const depth = request.depth ?? 1;
+    if (!Number.isInteger(depth) || depth < 1 || depth > MAX_DEPTH) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "depth is an integer from 1 to 10", { name: "depth", reason: "range" });
+    }
+    if (ids.length === 0) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "an expansion needs at least one id", { name: "ids", reason: "required" });
+    }
+    const limit = request.limit === undefined ? {} : { edgeLimit: request.limit, errorWhenLimitIsOver: false };
+    if (idAttribute !== undefined) {
+        if (!/^[A-Za-z_][\w.]*$/.test(idAttribute)) {
+            failOn(ctx.report, "E_SOURCE_PARAM", "idAttribute is not an attribute name", {
+                name: "idAttribute",
+                reason: "identifier",
+            });
+        }
+        const searchString = ids.map((id) => `${idAttribute}:${term(String(id))}`).join(" ");
+        return { searchString, searchDepth: depth, ...limit };
+    }
+    const nodeIds = ids.map(Number);
+    if (nodeIds.some((n) => !Number.isSafeInteger(n))) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "NDEx node ids are integers; set idAttribute to seed by name", {
+            name: "ids",
+            reason: "type",
+        });
+    }
+    return { searchString: "", searchDepth: depth, nodeIds, ...limit };
+}
+/**
+ * Fetch the neighborhood of some nodes of an NDEx network into a sink.
+ * @param request - the seeds, depth and limit; `limit` caps the edges NDEx returns
+ * @param sink - where to write
+ * @param ctx - the context
+ * @returns the report
+ */
+export async function expandNdex(request, sink, ctx) {
+    const uuid = checkedUuid(request.params.uuid, ctx);
+    if (request.direction !== undefined && request.direction !== "both") {
+        failOn(ctx.report, "E_SOURCE_UNSUPPORTED", "NDEx expands in both directions only", {
+            feature: "direction",
+            needs: "both",
+        });
+    }
+    if ((request.relationshipTypes ?? []).length > 0) {
+        failOn(ctx.report, "E_SOURCE_UNSUPPORTED", "NDEx cannot filter an expansion by relationship type", {
+            feature: "relationshipTypes",
+        });
+    }
+    const response = await ndexFetch(ctx, `v2/search/network/${uuid}/query`, uuid, {
+        method: "POST",
+        idempotent: true,
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify(queryBody(request, ctx)),
+    });
+    ctx.report.include(await cxImporter.import(response.body ?? "", sink, { signal: ctx.signal }));
+    return ctx.finish();
+}
+//# sourceMappingURL=expand.js.map

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

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

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

@@ -0,0 +1,25 @@
+/**
+ * `@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 { type GraphSource } from "../types.js";
+import { type NdexParams } from "./params.js";
+export { NDEX_DESCRIPTOR } from "./descriptor.js";
+export { type NdexParams } from "./params.js";
+export { type NdexShareLink, parseShareUrl } from "./share-url.js";
+/**
+ * The NDEx source. Experimental.
+ * @category Network sources
+ */
+export declare const ndexSource: GraphSource<NdexParams>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/sources/ndex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EACH,KAAK,WAAW,EAOnB,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAuHnE;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,UAAU,CA6E7C,CAAC"}