@graphty/graph-io 0.3.47 → 0.3.49

package/src/sources/cypher/profiles.ts

@@ -0,0 +1,78 @@
+/**
+ * What differs between openCypher servers (design section 12.2, "the profile"): the id
+ * expression, and the server facts `probe` reports. Everything else in the Cypher source is shared.
+ */
+
+/** The facts of one server the Cypher source talks to. */
+export interface CypherProfile {
+    /** "neo4j" or "neptune". */
+    readonly name: "neo4j" | "neptune";
+    /** true: ids are `elementId(n)` (Neo4j 5 and later); false: `id(n)` (Neo4j before 5, Neptune's `~id`). */
+    readonly elementIds: boolean;
+    /** The product, as the server names it. */
+    readonly product: string;
+    /** The server's version, when known. */
+    readonly version: string | null;
+    /** "enforced": the server refuses writes in this session; "not-enforced": nothing in the request does. */
+    readonly readOnly: "enforced" | "not-enforced";
+}
+
+/**
+ * The Neo4j profile for a version: `elementId()` from 5.0, `id()` before.
+ * @param version - the server's version, or null when not known (assumed 5 or later)
+ * @param product - the product name
+ * @returns the profile
+ */
+export function neo4jProfile(version: string | null, product = "Neo4j"): CypherProfile {
+    const major = version === null ? Number.NaN : Number.parseInt(version, 10);
+    return {
+        name: "neo4j",
+        elementIds: Number.isNaN(major) || major >= 5,
+        product,
+        version,
+        readOnly: "enforced",
+    };
+}
+
+/**
+ * The profile of a Bolt server from its agent string ("Neo4j/3.5.12"). A server that is not Neo4j
+ * gets `id()`, which every openCypher server has.
+ * @param agent - the server agent
+ * @returns the profile
+ */
+export function profileFromAgent(agent: string): CypherProfile {
+    const [product = "", version = ""] = agent.split("/");
+    if (product.toLowerCase() === "neo4j") {
+        return neo4jProfile(version === "" ? null : version);
+    }
+    return {
+        name: "neo4j",
+        elementIds: false,
+        product,
+        version: version === "" ? null : version,
+        readOnly: "enforced",
+    };
+}
+
+/**
+ * The Neptune profile: ids are `id(n)`, the `~id` string, never reused.
+ * @param version - the engine version, when known
+ * @returns the profile
+ */
+export function neptuneProfile(version: string | null = null): CypherProfile {
+    return { name: "neptune", elementIds: false, product: "Neptune", version, readOnly: "not-enforced" };
+}
+
+/**
+ * The server facts of a profile, as `probe` and `report.source.server` give them.
+ * @param profile - the profile
+ * @returns the facts
+ */
+export function serverFacts(profile: CypherProfile): Readonly<Record<string, string>> {
+    return {
+        product: profile.product,
+        profile: profile.name,
+        readOnly: profile.readOnly,
+        ...(profile.version === null ? {} : { version: profile.version }),
+    };
+}

package/src/sources/cypher/query-builder.ts

@@ -0,0 +1,327 @@
+/**
+ * The one query builder of the Cypher source (design sections 11 and 12.2). Caller values travel
+ * as query parameters, never spliced. What Cypher cannot parameterize -- labels, relationship
+ * types, property keys, variable-length bounds and LIMIT -- is either backtick-quoted (an
+ * identifier, a backtick inside doubled) or inlined as a checked integer. The generated queries
+ * differ between servers only in the id expression.
+ */
+
+import { type ImportReportBuilder } from "../../common/report.js";
+import { failAlone, failOn } from "../fail.js";
+import { type CypherProfile } from "./profiles.js";
+
+/** The deepest neighborhood a generated query asks for. */
+export const MAX_DEPTH = 10;
+
+/** The largest page of mode "all". */
+export const MAX_PAGE_SIZE = 100_000;
+
+/** The page size of mode "all" when the caller gives none. */
+export const DEFAULT_PAGE_SIZE = 1000;
+
+/**
+ * Why an identifier cannot be quoted, or null when it can.
+ * @param name - the identifier
+ * @returns the reason, or null
+ */
+function identifierProblem(name: unknown): string | null {
+    return typeof name !== "string" || name === "" || name.includes("\u0000") ? "identifier" : null;
+}
+
+/**
+ * Quote one Cypher identifier (a label, relationship type or property key) for a query: wrapped in
+ * backticks, with every backtick inside doubled, so no value can end the identifier early. An
+ * empty name, or one with a NUL character, is refused (E_SOURCE_PARAM, reason "identifier").
+ * Experimental.
+ * @param name - the identifier
+ * @returns the quoted identifier
+ * @example
+ * ```ts
+ * cypherIdentifier("Person"); // "`Person`"
+ * cypherIdentifier("odd`name"); // "`odd``name`"
+ * ```
+ * @category Network sources
+ */
+export function cypherIdentifier(name: string): string {
+    if (identifierProblem(name) !== null) {
+        failAlone("E_SOURCE_PARAM", "a Cypher identifier must be a non-empty string without NUL", {
+            name: "identifier",
+            reason: "identifier",
+        });
+    }
+    return `\`${name.replaceAll("`", "``")}\``;
+}
+
+/**
+ * Quote an identifier a parameter gave, failing the load when it cannot be.
+ * @param name - the identifier
+ * @param param - the parameter it came from
+ * @param report - the load's report
+ * @returns the quoted identifier
+ */
+export function quoted(name: unknown, param: string, report: ImportReportBuilder): string {
+    if (identifierProblem(name) !== null) {
+        failOn(report, "E_SOURCE_PARAM", `parameter ${param}: not a Cypher identifier`, {
+            name: param,
+            reason: "identifier",
+        });
+    }
+    return cypherIdentifier(name as string);
+}
+
+/**
+ * An integer to inline, checked to lie in its range.
+ * @param value - the value
+ * @param name - the parameter it came from
+ * @param min - the smallest allowed
+ * @param max - the largest allowed
+ * @param report - the load's report
+ * @returns the integer, as query text
+ */
+export function checkedInteger(
+    value: unknown,
+    name: string,
+    min: number,
+    max: number,
+    report: ImportReportBuilder,
+): string {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        failOn(report, "E_SOURCE_PARAM", `parameter ${name}: not an integer`, { name, reason: "type" });
+    }
+    if (value < min || value > max) {
+        failOn(report, "E_SOURCE_PARAM", `parameter ${name}: outside ${String(min)} to ${String(max)}`, {
+            name,
+            reason: "range",
+        });
+    }
+    return String(value);
+}
+
+/** What narrows a generated query: compiled into it, so filtering happens at the source. */
+export interface QueryFilters {
+    /** Quoted labels; a node must have one of them. */
+    readonly labels: readonly string[];
+    /** Quoted relationship types. */
+    readonly relationshipTypes: readonly string[];
+    /** The quoted id property, or null for the server's id. */
+    readonly idProperty: string | null;
+}
+
+/**
+ * The id expression of a node or relationship variable.
+ * @param v - the variable
+ * @param profile - the server's profile
+ * @param filters - the id property, for a node
+ * @param node - whether `v` is a node
+ * @returns the expression
+ */
+function idExpression(v: string, profile: CypherProfile, filters: QueryFilters, node = true): string {
+    if (node && filters.idProperty !== null) {
+        return `${v}.${filters.idProperty}`;
+    }
+    return profile.elementIds ? `elementId(${v})` : `id(${v})`;
+}
+
+/**
+ * The node predicate of the label and id property filters, or null.
+ * @param v - the node variable
+ * @param filters - the filters
+ * @returns the predicate
+ */
+function nodePredicate(v: string, filters: QueryFilters): string | null {
+    const parts: string[] = [];
+    if (filters.labels.length > 0) {
+        const prefix = `${v}:`;
+        parts.push(`(${filters.labels.map((l) => prefix + l).join(" OR ")})`);
+    }
+    if (filters.idProperty !== null) {
+        parts.push(`${v}.${filters.idProperty} IS NOT NULL`);
+    }
+    return parts.length === 0 ? null : parts.join(" AND ");
+}
+
+/**
+ * The relationship type part of a pattern: `:`A`|`B``, or "".
+ * @param filters - the filters
+ * @returns the pattern text
+ */
+function typesPattern(filters: QueryFilters): string {
+    return filters.relationshipTypes.length === 0 ? "" : `:${filters.relationshipTypes.join("|")}`;
+}
+
+/**
+ * The degree hint of a node variable: its relationship count, by pattern comprehension.
+ * @param v - the variable
+ * @returns the expression
+ */
+function degreeOf(v: string): string {
+    return `size([(${v})--() | 1])`;
+}
+
+/** The arrows of each direction around a relationship pattern. */
+const ARROWS = { out: ["-", "->"], in: ["<-", "-"], both: ["-", "-"] } as const;
+
+/**
+ * One page of the nodes of mode "all", ordered by the id expression (keyset paging, never SKIP).
+ * @param profile - the server's profile
+ * @param filters - the filters
+ * @param pageSize - the checked page size, as text
+ * @param after - whether the page starts after `$after`
+ * @param degree - whether to add the degree hint
+ * @returns the statement; it reads `$after`
+ */
+export function nodePage(
+    profile: CypherProfile,
+    filters: QueryFilters,
+    pageSize: string,
+    after: boolean,
+    degree: boolean,
+): string {
+    const where = nodePredicate("n", filters);
+    return [
+        "MATCH (n)",
+        where === null ? null : `WHERE ${where}`,
+        `WITH n, ${idExpression("n", profile, filters)} AS key`,
+        after ? "WHERE key > $after" : null,
+        degree ? `RETURN n, key, ${degreeOf("n")} AS degree` : "RETURN n, key",
+        `ORDER BY key LIMIT ${pageSize}`,
+    ]
+        .filter((l) => l !== null)
+        .join(" ");
+}
+
+/**
+ * One page of the relationships of mode "all", with their end nodes, ordered by the relationship
+ * id expression.
+ * @param profile - the server's profile
+ * @param filters - the filters
+ * @param pageSize - the checked page size, as text
+ * @param after - whether the page starts after `$after`
+ * @returns the statement; it reads `$after`
+ */
+export function edgePage(profile: CypherProfile, filters: QueryFilters, pageSize: string, after: boolean): string {
+    const a = nodePredicate("a", filters);
+    const b = nodePredicate("b", filters);
+    const where = [a, b].filter((p) => p !== null);
+    return [
+        `MATCH (a)-[r${typesPattern(filters)}]->(b)`,
+        where.length === 0 ? null : `WHERE ${where.join(" AND ")}`,
+        `WITH a, r, b, ${idExpression("r", profile, filters, false)} AS key`,
+        after ? "WHERE key > $after" : null,
+        "RETURN a, r, b, key",
+        `ORDER BY key LIMIT ${pageSize}`,
+    ]
+        .filter((l) => l !== null)
+        .join(" ");
+}
+
+/**
+ * The relationships among the nodes a capped mode "all" has loaded: both ends at or before the
+ * node page's last key `$last`, and, after the first page, one end past the previous page's last
+ * key `$after`, so each relationship arrives with the page that loads its later end.
+ * @param profile - the server's profile
+ * @param filters - the filters
+ * @param after - whether earlier pages were loaded
+ * @returns the statement; it reads `$last` and `$after`
+ */
+export function edgesAmong(profile: CypherProfile, filters: QueryFilters, after: boolean): string {
+    const where = [nodePredicate("a", filters), nodePredicate("b", filters)].filter((p) => p !== null);
+    return [
+        `MATCH (a)-[r${typesPattern(filters)}]->(b)`,
+        where.length === 0 ? null : `WHERE ${where.join(" AND ")}`,
+        `WITH a, r, b, ${idExpression("a", profile, filters)} AS ka, ${idExpression("b", profile, filters)} AS kb`,
+        `WHERE ka <= $last AND kb <= $last${after ? " AND (ka > $after OR kb > $after)" : ""}`,
+        "RETURN a, r, b",
+    ]
+        .filter((l) => l !== null)
+        .join(" ");
+}
+
+/** How far a neighborhood reaches. */
+interface NeighborhoodShape {
+    /** The checked depth, as text. */
+    readonly depth: string;
+    /** Which way relationships are followed. */
+    readonly direction: "out" | "in" | "both";
+    /** The checked path limit, as text, or null for none. */
+    readonly limit: string | null;
+    /** Whether the page starts after the neighbor key `$after` (a capped expansion's next page). */
+    readonly after?: boolean;
+}
+
+/**
+ * The neighborhood of the seeds `$ids`: every path up to `depth` hops, each seed included even with
+ * no neighbor, plus the degree of every node returned.
+ * @param profile - the server's profile
+ * @param filters - the filters
+ * @param shape - depth, direction and limit
+ * @param degree - whether to add the degree hint
+ * @returns the statement; it reads `$ids`
+ */
+export function neighborhood(
+    profile: CypherProfile,
+    filters: QueryFilters,
+    shape: NeighborhoodShape,
+    degree: boolean,
+): string {
+    const rel = `[${typesPattern(filters)}*1..${shape.depth}]`;
+    const [left, right] = ARROWS[shape.direction];
+    const pattern = `${left}${rel}${right}`;
+    const x = nodePredicate("x", filters);
+    const degrees = degree
+        ? `, [m IN CASE WHEN p IS NULL THEN [s] ELSE nodes(p) END | [${idExpression("m", profile, filters)}, ${degreeOf("m")}]] AS degrees`
+        : "";
+    // A capped expansion is ordered by the neighbor's key, so its next page starts after the last
+    // key it returned. ponytail: a page boundary falling between two paths to the same neighbor
+    // (parallel relationships, or depth > 1) drops the later paths; page on (key, path) if that matters.
+    const head = [
+        `MATCH (s) WHERE ${idExpression("s", profile, filters)} IN $ids`,
+        `OPTIONAL MATCH p = (s)${pattern}(x)${whereClause(x)}`,
+    ];
+    if (shape.limit === null) {
+        return [...head, "WITH s, p", `RETURN s, p${degrees}`].join(" ");
+    }
+    return [
+        ...head,
+        `WITH s, p, ${idExpression("x", profile, filters)} AS key`,
+        shape.after === true ? "WHERE key > $after" : null,
+        `WITH s, p, key ORDER BY key LIMIT ${shape.limit}`,
+        `RETURN s, p, key${degrees}`,
+    ]
+        .filter((l) => l !== null)
+        .join(" ");
+}
+
+/**
+ * A ` WHERE` clause for a predicate.
+ * @param predicate - the predicate, or null
+ * @returns the clause with its leading space, or "" for no predicate
+ */
+function whereClause(predicate: string | null): string {
+    return predicate === null ? "" : ` WHERE ${predicate}`;
+}
+
+/**
+ * The counts of mode "all", for a progress total.
+ * @param filters - the filters
+ * @returns two statements: the nodes, then the relationships
+ */
+export function counts(filters: QueryFilters): readonly [string, string] {
+    const n = nodePredicate("n", filters);
+    const where = [nodePredicate("a", filters), nodePredicate("b", filters)].filter((p) => p !== null);
+    return [
+        `MATCH (n)${whereClause(n)} RETURN count(n) AS c`,
+        `MATCH (a)-[r${typesPattern(filters)}]->(b)${whereClause(where.length === 0 ? null : where.join(" AND "))} RETURN count(r) AS c`,
+    ];
+}
+
+/**
+ * The node count of a mode "all" load with at most one label and the server's ids: a pattern
+ * Neo4j answers from its count store in one cheap lookup, whatever the graph's size.
+ * @param label - the quoted label, or undefined for every node
+ * @returns the statement
+ */
+export function storeCount(label: string | undefined): string {
+    const pattern = label === undefined ? "n" : `n:${label}`;
+    return `MATCH (${pattern}) RETURN count(n) AS c`;
+}

package/src/sources/cypher/transports/bolt.ts

@@ -0,0 +1,228 @@
+/**
+ * The `bolt` transport (design sections 9 and 12.2): the official neo4j-driver, an optional peer
+ * dependency imported only here. Absent, a load fails with E_SOURCE_RUNTIME (`reason:
+ * "needs-peer-dependency"`). It is the only path to a Neo4j older than 5.26, such as Hetionet's 3.5.
+ *
+ * - Direct connections only (`bolt:`, `bolt+s:`, `bolt+ssc:`): a routing scheme would send the
+ *   credential to every host the routing table lists, so `neo4j:` schemes are refused.
+ * - `+ssc` accepts any certificate, so it is refused with a credential; plain `bolt:` is refused
+ *   with one unless the host is this machine or `allowInsecure` is set.
+ * - Statements run as auto-commit `session.run` in a READ session, never as managed transactions,
+ *   which retry a server timeout for 30 s.
+ * - Integers stay lossless and are converted by the type mapper; the signal closes the session.
+ */
+
+import { throwIfAborted } from "../../../common/input.js";
+import { isLoopback, transportOptions } from "../../context.js";
+import { originOf, unwrapCredential } from "../../credentials.js";
+import { failOn } from "../../fail.js";
+import { type QueryResult } from "../flatten.js";
+import { type CypherProfile, profileFromAgent } from "../profiles.js";
+import { type DriverTypes, fromDriver } from "../types-map.js";
+import { serverError, type Transport, type TransportInput } from "./transport.js";
+
+/** The optional peer dependency. */
+const DRIVER_PACKAGE = "neo4j-driver";
+
+/** The URL schemes of a direct Bolt connection. */
+const DIRECT_SCHEMES = new Set(["bolt:", "bolt+s:", "bolt+ssc:"]);
+
+/** The parts of a neo4j-driver session this transport uses. */
+interface DriverSession {
+    run(
+        statement: string,
+        parameters: Readonly<Record<string, unknown>>,
+        config?: { readonly timeout?: number },
+    ): Promise<{
+        readonly records: readonly { readonly keys: readonly PropertyKey[]; get(key: PropertyKey): unknown }[];
+    }>;
+    close(): Promise<void>;
+}
+
+/** The parts of a neo4j-driver driver this transport uses. */
+interface Driver {
+    session(config: { readonly defaultAccessMode: string; readonly database?: string }): DriverSession;
+    getServerInfo(): Promise<{ readonly agent?: string }>;
+    close(): Promise<void>;
+}
+
+/** The parts of the neo4j-driver module this transport uses. */
+interface DriverModule extends DriverTypes {
+    driver(url: string, auth?: unknown, config?: Readonly<Record<string, unknown>>): Driver;
+    readonly auth: { basic(user: string, password: string): unknown; bearer(token: string): unknown };
+    readonly session: { readonly READ: string };
+}
+
+/**
+ * Import the optional peer dependency.
+ * @param input - the transport input
+ * @returns the driver module
+ */
+async function loadDriver(input: TransportInput): Promise<DriverModule> {
+    let mod: { default?: DriverModule } & Partial<DriverModule>;
+    try {
+        mod = (await import("neo4j-driver")) as unknown as typeof mod;
+    } catch {
+        return failOn(input.ctx.report, "E_SOURCE_RUNTIME", `the bolt transport needs ${DRIVER_PACKAGE} installed`, {
+            runtime: input.ctx.runtime,
+            reason: "needs-peer-dependency",
+            package: DRIVER_PACKAGE,
+        });
+    }
+    return mod.default ?? (mod as DriverModule);
+}
+
+/**
+ * Fail when an https page would open a plain Bolt WebSocket to another machine, which the browser
+ * blocks.
+ * @param ctx - the context
+ * @param url - the endpoint
+ */
+function refuseMixedContent(ctx: TransportInput["ctx"], url: URL): void {
+    const page = (globalThis as { location?: { protocol?: string } }).location;
+    if (
+        ctx.runtime === "browser" &&
+        page?.protocol === "https:" &&
+        url.protocol === "bolt:" &&
+        !isLoopback(url.hostname)
+    ) {
+        failOn(ctx.report, "E_SOURCE_RUNTIME", "an https page cannot open a plain Bolt WebSocket", {
+            runtime: ctx.runtime,
+            reason: "insecure-endpoint",
+        });
+    }
+}
+
+/**
+ * Check the endpoint and the credential before connecting, and turn the credential into the
+ * driver's auth token.
+ * @param input - the transport input
+ * @param neo4j - the driver module
+ * @returns the URL and auth token
+ */
+async function connection(input: TransportInput, neo4j: DriverModule): Promise<{ url: URL; auth: unknown }> {
+    const { ctx } = input;
+    const { report } = ctx;
+    const bad = (reason: string, message: string): never =>
+        failOn(report, "E_SOURCE_PARAM", message, { name: "endpoint", reason });
+    const url = ctx.endpoint ?? bad("missing", "the bolt transport needs an endpoint");
+    if (!DIRECT_SCHEMES.has(url.protocol)) {
+        bad(url.protocol.startsWith("neo4j") ? "routing" : "scheme", `${url.protocol} is not a direct Bolt scheme`);
+    }
+    refuseMixedContent(ctx, url);
+    const { credential, allowInsecure } = transportOptions(ctx);
+    const origin = originOf(url);
+    const bound = credential !== undefined && (credential.origins.length === 0 || credential.origins.includes(origin));
+    if (!bound || credential === undefined) {
+        return { url, auth: undefined };
+    }
+    if (url.protocol === "bolt+ssc:") {
+        bad("unverified-tls", "bolt+ssc accepts any certificate, so no credential is sent over it");
+    }
+    if (url.protocol === "bolt:" && !isLoopback(url.hostname) && allowInsecure !== true) {
+        bad("insecure-endpoint", "a credential is never sent without TLS");
+    }
+    const secret = unwrapCredential(credential);
+    if (secret !== undefined && "username" in secret) {
+        return { url, auth: neo4j.auth.basic(secret.username, secret.password) };
+    }
+    if (secret !== undefined && "token" in secret) {
+        const token = typeof secret.token === "string" ? secret.token : await secret.token();
+        return { url, auth: neo4j.auth.bearer(token) };
+    }
+    return failOn(report, "E_SOURCE_PARAM", "the bolt transport takes a basic or bearer credential", {
+        name: "credential",
+        reason: "kind",
+    });
+}
+
+/**
+ * Make the transport: import the driver, check the endpoint and credential, open a READ session.
+ * @param input - the context, params and mapper
+ * @returns the transport
+ */
+export async function boltTransport(input: TransportInput): Promise<Transport> {
+    const { ctx, params, m } = input;
+    throwIfAborted(ctx.signal);
+    const neo4j = await loadDriver(input);
+    const { url, auth } = await connection(input, neo4j);
+    throwIfAborted(ctx.signal);
+    const origin = originOf(url);
+    const { userAgent } = transportOptions(ctx);
+    const driver = neo4j.driver(`${url.protocol}//${url.host}`, auth, userAgent === undefined ? {} : { userAgent });
+    const session = driver.session({
+        defaultAccessMode: neo4j.session.READ,
+        ...(params.database === undefined ? {} : { database: params.database }),
+    });
+    let closed: Promise<void> | null = null;
+    const close = (): Promise<void> => {
+        closed ??= session
+            .close()
+            .catch(() => undefined)
+            .then(() => driver.close())
+            .catch(() => undefined);
+        return closed;
+    };
+    const onAbort = (): void => {
+        void close();
+    };
+    ctx.signal.addEventListener("abort", onAbort, { once: true });
+
+    const fail = (err: unknown): never => {
+        throwIfAborted(ctx.signal);
+        const e = err as { code?: unknown; message?: unknown };
+        const code = typeof e.code === "string" ? e.code : null;
+        if (code === null || code === "ServiceUnavailable" || code === "SessionExpired") {
+            return ctx.runtime === "browser"
+                ? failOn(ctx.report, "E_SOURCE_BLOCKED", `${origin} could not be reached over Bolt`, {
+                      url: origin,
+                      cause: "unknown",
+                  })
+                : failOn(ctx.report, "E_FETCH", `${origin} could not be reached over Bolt`, {
+                      url: origin,
+                      status: null,
+                  });
+        }
+        return serverError(
+            ctx.report,
+            {
+                code,
+                message: typeof e.message === "string" ? e.message : "",
+                status: null,
+                showable: code.startsWith("Neo.ClientError."),
+            },
+            origin,
+            params.database,
+        );
+    };
+
+    let detected: CypherProfile | null = null;
+    const profile = async (): Promise<CypherProfile> => {
+        if (detected === null) {
+            const info = await driver.getServerInfo().catch(fail);
+            detected = profileFromAgent(info.agent ?? "");
+        }
+        return detected;
+    };
+    const timeout = ctx.limits.timeoutMs;
+
+    return {
+        async run(statement, parameters): Promise<QueryResult> {
+            throwIfAborted(ctx.signal);
+            const result = await session
+                .run(statement, parameters, timeout === undefined ? undefined : { timeout })
+                .catch(fail);
+            const fields = (result.records[0]?.keys ?? []).map(String);
+            return {
+                fields,
+                rows: result.records.map((r) => fields.map((k) => fromDriver(r.get(k), k, m, neo4j))),
+            };
+        },
+        profile,
+        probe: profile,
+        close: async (): Promise<void> => {
+            ctx.signal.removeEventListener("abort", onAbort);
+            await close();
+        },
+    };
+}

package/src/sources/cypher/transports/neptune-analytics.ts

@@ -0,0 +1,41 @@
+/**
+ * The `neptune-analytics` transport (design section 12.4): `POST /queries` on the graph's host
+ * (`<graph-id>.<region>.neptune-graph.amazonaws.com`), JSON `{ query, language: "OPEN_CYPHER",
+ * parameters }`, always signed with `credentials.awsSigV4` for the service "neptune-graph".
+ * Results share Neptune Database's `~id` shape. Node only until CORS on a graph host is shown to
+ * work: a browser is refused before any request (E_SOURCE_RUNTIME, reason "cors").
+ */
+
+import { type QueryResult } from "../flatten.js";
+import { neptuneProfile } from "../profiles.js";
+import { neptuneResult, nodeOnly } from "./neptune-https.js";
+import { type Transport, type TransportInput } from "./transport.js";
+
+/**
+ * Make the transport.
+ * @param input - the context, params and mapper
+ * @returns the transport
+ */
+export function neptuneAnalyticsTransport(input: TransportInput): Transport {
+    const { ctx } = input;
+    nodeOnly(ctx, "neptune-analytics");
+    const run = async (statement: string, parameters: Readonly<Record<string, unknown>>): Promise<QueryResult> => {
+        const response = await ctx.fetch("queries", {
+            method: "POST",
+            idempotent: true,
+            allowStatus: [400, 500],
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query: statement, language: "OPEN_CYPHER", parameters }),
+        });
+        return neptuneResult(input, response);
+    };
+    return {
+        run,
+        profile: () => Promise.resolve(neptuneProfile()),
+        probe: async () => {
+            await run("RETURN 1 AS ok", {});
+            return neptuneProfile();
+        },
+        close: () => Promise.resolve(),
+    };
+}