tina4-nodejs 3.13.110 → 3.13.112

package/packages/orm/src/graph/adapters/ultipa.ts

@@ -0,0 +1,271 @@
+/**
+ * Ultipa graph adapter — the portable core built in GQL over the tina4-ultipa driver.
+ *
+ * Wraps the standalone `tina4-ultipa` driver (an OPTIONAL dependency — imported at
+ * the top of THIS module only, so `import "@tina4/orm"` stays driver-free; the
+ * GraphDatabase factory dynamically imports this module and turns a missing driver
+ * into the actionable install error). The portable node/edge/traverse surface is
+ * expressed in Ultipa GQL on top of the driver's query()/execute(); raw
+ * query()/execute() send GQL straight through.
+ *
+ * GQL note: the exact statements are verified against the live Ultipa community
+ * edition on the lab (no mocks). Ultipa node ids are the engine's own UUID strings;
+ * we echo back whatever id(n)/id(e) returns without assuming a type. Reads go via
+ * query() (readOnly=true); writes via execute() (readOnly=false) — a write through
+ * query() is rejected by Ultipa.
+ */
+import { GraphNode, GraphEdge, GraphResult } from "../shapes.js";
+import { GraphError, GraphConnectTimeout } from "../errors.js";
+import {
+  resolveGraphConnectTimeout,
+  GRAPH_CONNECT_TIMEOUT_VARIABLE,
+} from "../connectTimeout.js";
+import type { GraphUrl } from "../graphUrl.js";
+import type { GraphCredentials } from "../graphDatabase.js";
+import type {
+  GraphAdapter,
+  NeighborOptions,
+  TraverseOptions,
+} from "../graphAdapter.js";
+
+/**
+ * The driver package name as a VARIABLE, so TypeScript does not try to resolve a
+ * package that is only installed when the Ultipa engine is actually used. This
+ * top-level await is what makes an absent driver surface as the factory's
+ * actionable install error (the dynamic import of this module rejects).
+ */
+const DRIVER_PACKAGE = "tina4-ultipa";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const driver: any = await import(DRIVER_PACKAGE);
+const UltipaClient = driver.UltipaClient;
+const UltipaConnectError = driver.UltipaConnectError;
+
+/**
+ * Seconds handed to the driver when the bound is disabled (resolver returns null).
+ * The driver arms a real gRPC deadline (now + seconds*1000), so "unbounded" is a
+ * far-future finite deadline rather than 0 — which the driver would read as an
+ * instant, already-past deadline.
+ */
+const UNBOUNDED_CONNECT_SECONDS = 315_360_000; // ~10 years
+
+interface DriverRow {
+  id?: unknown;
+  labels?: unknown;
+  props?: unknown;
+  type?: unknown;
+  f?: unknown;
+  t?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Build a GQL property map `{k1: $p_k1, ...}` plus the param dict for it.
+ *
+ * Params are BOUND (never interpolated), matching the relational ?-placeholder
+ * rule. Keys are namespaced (`p_`) so they never collide with an id param.
+ */
+function propClause(
+  properties: Record<string, unknown> | null | undefined,
+): { clause: string; params: Record<string, unknown> } {
+  const props = properties ?? {};
+  const keys = Object.keys(props);
+  if (keys.length === 0) return { clause: "{}", params: {} };
+  const pairs = keys.map((key) => `${key}: $p_${key}`).join(", ");
+  const params: Record<string, unknown> = {};
+  for (const key of keys) params[`p_${key}`] = props[key];
+  return { clause: `{${pairs}}`, params };
+}
+
+function errorMessage(exc: unknown): string {
+  if (exc instanceof Error) return exc.message;
+  return String(exc);
+}
+
+export class UltipaGraphAdapter implements GraphAdapter {
+  private readonly url: GraphUrl;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private readonly client: any;
+  private lastError: string | null = null;
+
+  constructor(graphUrl: GraphUrl, credentials: GraphCredentials = {}) {
+    this.url = graphUrl;
+    const timeout = resolveGraphConnectTimeout();
+    this.client = new UltipaClient({
+      host: graphUrl.host,
+      port: graphUrl.port,
+      username: graphUrl.username || credentials.username || null,
+      password: graphUrl.password || credentials.password || null,
+      graph: graphUrl.graph,
+      connectTimeout: timeout ?? UNBOUNDED_CONNECT_SECONDS,
+      useTls: graphUrl.useTls,
+    });
+  }
+
+  // -- connection + raw pass-through -------------------------------------
+  private async run(
+    gql: string,
+    params: Record<string, unknown> | null = null,
+    readOnly = true,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any> {
+    try {
+      await this.client.connect();
+    } catch (exc) {
+      this.lastError = errorMessage(exc);
+      if (exc instanceof UltipaConnectError || (exc as { name?: string })?.name === "UltipaConnectError") {
+        const elapsed = typeof (exc as { elapsed?: number })?.elapsed === "number"
+          ? (exc as { elapsed: number }).elapsed
+          : 0;
+        throw new GraphConnectTimeout(
+          `Graph connect to ${this.url.host}:${this.url.port} timed out after ${elapsed.toFixed(1)}s `
+          + `(${GRAPH_CONNECT_TIMEOUT_VARIABLE}). Raise ${GRAPH_CONNECT_TIMEOUT_VARIABLE} if the server `
+          + `is simply slow, or set it to 0 to wait indefinitely.`,
+          exc,
+        );
+      }
+      // A non-timeout connect failure (auth, protocol) still fails loud.
+      throw new GraphError(this.lastError, exc);
+    }
+    try {
+      return await this.client.query(gql, { params: params ?? null, readOnly });
+    } catch (exc) {
+      this.lastError = errorMessage(exc);
+      throw new GraphError(this.lastError, exc);
+    }
+  }
+
+  async query(text: string, params: Record<string, unknown> | null = null): Promise<GraphResult> {
+    const result = await this.run(text, params, true);
+    return new GraphResult(result.dicts(), result.columns);
+  }
+
+  async execute(text: string, params: Record<string, unknown> | null = null): Promise<GraphResult> {
+    const result = await this.run(text, params, false);
+    return new GraphResult(result.dicts(), result.columns);
+  }
+
+  // -- portable node/edge/traverse core (GQL) ----------------------------
+  private nodeFromRow(row: DriverRow | undefined | null): GraphNode | null {
+    if (row === null || row === undefined) return null;
+    return new GraphNode(
+      String(row.id),
+      (row.labels as string[]) ?? [],
+      (row.props as Record<string, unknown>) ?? {},
+    );
+  }
+
+  async addNode(
+    label: string,
+    properties: Record<string, unknown> | null = null,
+  ): Promise<GraphNode | null> {
+    const { clause, params } = propClause(properties);
+    const gql =
+      `INSERT (n:\`${label}\` ${clause}) `
+      + `RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props`;
+    const rows = (await this.run(gql, params, false)).dicts() as DriverRow[];
+    return rows.length ? this.nodeFromRow(rows[0]) : null;
+  }
+
+  async addEdge(
+    fromId: string,
+    toId: string,
+    type: string,
+    properties: Record<string, unknown> | null = null,
+  ): Promise<GraphEdge | null> {
+    // id(e) requires EDGE_ID enabled on the Ultipa graph
+    // (`ALTER GRAPH <g> SET EDGE_ID ENABLED`), a one-time per-graph setting.
+    const { clause, params } = propClause(properties);
+    params.from_id = fromId;
+    params.to_id = toId;
+    const gql =
+      `MATCH (a), (b) WHERE id(a) = $from_id AND id(b) = $to_id `
+      + `INSERT (a)-[e:\`${type}\` ${clause}]->(b) `
+      + `RETURN id(e) AS id, type(e) AS type, id(a) AS f, id(b) AS t, properties(e) AS props`;
+    const rows = (await this.run(gql, params, false)).dicts() as DriverRow[];
+    if (rows.length === 0) return null;
+    const row = rows[0];
+    return new GraphEdge(
+      String(row.id),
+      String(row.type),
+      String(row.f),
+      String(row.t),
+      (row.props as Record<string, unknown>) ?? {},
+    );
+  }
+
+  async getNode(nodeId: string): Promise<GraphNode | null> {
+    const gql =
+      `MATCH (n) WHERE id(n) = $id `
+      + `RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props`;
+    const rows = (await this.run(gql, { id: nodeId }, true)).dicts() as DriverRow[];
+    return rows.length ? this.nodeFromRow(rows[0]) : null;
+  }
+
+  async updateNode(
+    nodeId: string,
+    properties: Record<string, unknown>,
+  ): Promise<GraphNode | null> {
+    const props = properties ?? {};
+    const keys = Object.keys(props);
+    const sets = keys.map((key) => `n.${key} = $p_${key}`).join(", ");
+    const params: Record<string, unknown> = { id: nodeId };
+    for (const key of keys) params[`p_${key}`] = props[key];
+    const gql =
+      `MATCH (n) WHERE id(n) = $id SET ${sets} `
+      + `RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props`;
+    const rows = (await this.run(gql, params, false)).dicts() as DriverRow[];
+    return rows.length ? this.nodeFromRow(rows[0]) : null;
+  }
+
+  async deleteNode(nodeId: string): Promise<boolean> {
+    const gql = "MATCH (n) WHERE id(n) = $id DETACH DELETE n";
+    await this.run(gql, { id: nodeId }, false);
+    return true;
+  }
+
+  async neighbors(nodeId: string, options: NeighborOptions = {}): Promise<GraphNode[]> {
+    const direction = options.direction ?? "both";
+    const limit = options.limit ?? 100;
+    const edge = options.edgeType ? `:\`${options.edgeType}\`` : "";
+    const pattern = {
+      out: `(n)-[${edge}]->(m)`,
+      in: `(n)<-[${edge}]-(m)`,
+      both: `(n)-[${edge}]-(m)`,
+    }[direction];
+    const gql =
+      `MATCH ${pattern} WHERE id(n) = $id `
+      + `RETURN DISTINCT id(m) AS id, labels(m) AS labels, properties(m) AS props `
+      + `LIMIT ${Math.trunc(limit)}`;
+    const rows = (await this.run(gql, { id: nodeId }, true)).dicts() as DriverRow[];
+    return rows.map((row) => this.nodeFromRow(row)!).filter((node) => node !== null);
+  }
+
+  async traverse(startId: string, options: TraverseOptions = {}): Promise<GraphNode[]> {
+    // Ultipa GQL uses the ISO quantified-path form `-[]->{1,N}`, NOT Cypher's
+    // `-[*1..N]->` (which is a parse error on gqldb).
+    const depth = options.depth ?? 1;
+    const direction = options.direction ?? "both";
+    const limit = options.limit ?? 1000;
+    const edge = options.edgeType ? `:\`${options.edgeType}\`` : "";
+    const quant = `{1,${Math.trunc(depth)}}`;
+    const pattern = {
+      out: `(n)-[${edge}]->${quant}(m)`,
+      in: `(n)<-[${edge}]-${quant}(m)`,
+      both: `(n)-[${edge}]-${quant}(m)`,
+    }[direction];
+    const gql =
+      `MATCH ${pattern} WHERE id(n) = $start `
+      + `RETURN DISTINCT id(m) AS id, labels(m) AS labels, properties(m) AS props `
+      + `LIMIT ${Math.trunc(limit)}`;
+    const rows = (await this.run(gql, { start: startId }, true)).dicts() as DriverRow[];
+    return rows.map((row) => this.nodeFromRow(row)!).filter((node) => node !== null);
+  }
+
+  close(): void {
+    this.client.close();
+  }
+
+  getError(): string | null {
+    return this.lastError;
+  }
+}

package/packages/orm/src/graph/connectTimeout.ts

@@ -0,0 +1,39 @@
+/**
+ * TINA4_GRAPH_CONNECT_TIMEOUT — the graph connect bound.
+ *
+ * The sibling of TINA4_DATABASE_CONNECT_TIMEOUT: seconds a graph connect may
+ * block. A value <= 0 disables the bound (unbounded); a non-number warns and
+ * falls back to the default rather than waiting forever. Same contract in all
+ * four frameworks.
+ */
+import { Log } from "../../../core/src/index.js";
+
+/** The env var name — one spelling, so grepping finds every reader. */
+export const GRAPH_CONNECT_TIMEOUT_VARIABLE = "TINA4_GRAPH_CONNECT_TIMEOUT";
+
+/** Seconds. Long enough for a cold connect, short enough to page. */
+export const DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS = 10;
+
+/**
+ * Seconds a graph connect may block, or `null` when the bound is disabled (<= 0).
+ *
+ * Mirrors resolveConnectTimeout: a value <= 0 disables the bound, a non-number
+ * warns and uses the default. Seconds is the operator-facing unit (the Ultipa
+ * driver takes seconds), so no ms conversion happens here.
+ */
+export function resolveGraphConnectTimeout(): number | null {
+  const raw = (process.env[GRAPH_CONNECT_TIMEOUT_VARIABLE] ?? "").trim();
+  if (raw === "") {
+    return DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS;
+  }
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds)) {
+    Log.warning(
+      `${GRAPH_CONNECT_TIMEOUT_VARIABLE}="${raw}" is not a number of seconds — `
+      + `bounding graph connects at the ${DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS}s default instead`,
+    );
+    return DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS;
+  }
+  // <= 0 is a deliberate opt-out, not a typo: unbounded, wait indefinitely.
+  return seconds <= 0 ? null : seconds;
+}

package/packages/orm/src/graph/errors.ts

@@ -0,0 +1,29 @@
+/**
+ * Graph layer errors — the graph siblings of the relational fail-loud contract.
+ *
+ * A bad graph statement RAISES (never a falsy return); the cause is readable via
+ * the adapter's getError() after the throw. An unreachable host throws
+ * GraphConnectTimeout within TINA4_GRAPH_CONNECT_TIMEOUT, naming host and port.
+ */
+
+/** A graph operation failed (bad statement, engine error). */
+export class GraphError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "GraphError";
+  }
+}
+
+/**
+ * A graph connect exceeded TINA4_GRAPH_CONNECT_TIMEOUT.
+ *
+ * The message names the host, the port and the elapsed seconds — the mirror of
+ * the relational DatabaseConnectTimeout, so an operator can tell "my bound
+ * fired" apart from "the engine rejected me".
+ */
+export class GraphConnectTimeout extends GraphError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = "GraphConnectTimeout";
+  }
+}

package/packages/orm/src/graph/graphAdapter.ts

@@ -0,0 +1,53 @@
+/**
+ * The one surface every graph engine implements.
+ *
+ * The portable node/edge/traverse core PLUS a raw query()/execute() pass-through
+ * in the engine's native dialect, and lifecycle. Every method is async — the
+ * Node graph drivers are async (gRPC/Bolt/HTTP), so the surface is async
+ * everywhere, matching the relational Database wrapper. See ADR-0059.
+ */
+import type { GraphNode, GraphEdge, GraphResult } from "./shapes.js";
+
+/** Direction of an edge relative to the anchor node. */
+export type GraphDirection = "out" | "in" | "both";
+
+/** Options for the one-hop neighbours read. */
+export interface NeighborOptions {
+  direction?: GraphDirection;
+  edgeType?: string;
+  limit?: number;
+}
+
+/** Options for the bounded multi-hop traversal. */
+export interface TraverseOptions {
+  depth?: number;
+  direction?: GraphDirection;
+  edgeType?: string;
+  limit?: number;
+}
+
+export interface GraphAdapter {
+  // -- portable node/edge/traverse core ----------------------------------
+  addNode(label: string, properties?: Record<string, unknown> | null): Promise<GraphNode | null>;
+  addEdge(
+    fromId: string,
+    toId: string,
+    type: string,
+    properties?: Record<string, unknown> | null,
+  ): Promise<GraphEdge | null>;
+  getNode(nodeId: string): Promise<GraphNode | null>;
+  updateNode(nodeId: string, properties: Record<string, unknown>): Promise<GraphNode | null>;
+  deleteNode(nodeId: string): Promise<boolean>;
+  neighbors(nodeId: string, options?: NeighborOptions): Promise<GraphNode[]>;
+  traverse(startId: string, options?: TraverseOptions): Promise<GraphNode[]>;
+
+  // -- raw pass-through (engine-native dialect) --------------------------
+  query(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+  execute(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+
+  // -- lifecycle ---------------------------------------------------------
+  close(): Promise<void> | void;
+
+  /** Cause of the last failed operation, or null. */
+  getError(): string | null;
+}

package/packages/orm/src/graph/graphDatabase.ts

@@ -0,0 +1,114 @@
+/**
+ * The GraphAdapter URL-selected factory — the GraphDatabase sibling of Database.
+ *
+ * GraphDatabase.create picks an adapter by URL scheme and imports its driver
+ * lazily (dynamic import): a missing driver raises an actionable install error,
+ * never a bare module-not-found, and the graph CORE imports with no driver
+ * present (the zero-dependency-core rule). The barrel deliberately does NOT
+ * re-export any engine adapter, so importing @tina4/orm pulls in no graph driver.
+ */
+import { GraphUrl, type GraphEngine } from "./graphUrl.js";
+import { GraphError } from "./errors.js";
+import type { GraphAdapter } from "./graphAdapter.js";
+
+/** Credentials passed alongside the URL when it carries none. */
+export interface GraphCredentials {
+  username?: string;
+  password?: string;
+}
+
+export interface AdapterRegistration {
+  /** Dynamic import of the adapter module — the ONLY place a driver is pulled. */
+  load: () => Promise<Record<string, unknown>>;
+  className: string;
+  /** npm package that provides the engine driver. */
+  package: string;
+  /** The command that installs it. */
+  installCommand: string;
+}
+
+/**
+ * engine -> adapter registration. Selected lazily so importing this module pulls
+ * in NO engine driver. bolt (Neo4j/Memgraph) and arango land later — declared so
+ * the factory gives an actionable message rather than a bare KeyError.
+ */
+export const ENGINE_ADAPTERS: Partial<Record<GraphEngine, AdapterRegistration>> = {
+  ultipa: {
+    load: () => import("./adapters/ultipa.js") as Promise<Record<string, unknown>>,
+    className: "UltipaGraphAdapter",
+    package: "tina4-ultipa",
+    installCommand: "npm install tina4-ultipa",
+  },
+  bolt: {
+    // Neo4j AND Memgraph — both speak Bolt/Cypher over the neo4j-driver package.
+    load: () => import("./adapters/bolt.js") as Promise<Record<string, unknown>>,
+    className: "BoltGraphAdapter",
+    package: "neo4j-driver",
+    installCommand: "npm install neo4j-driver",
+  },
+  arango: {
+    load: () => import("./adapters/arango.js") as Promise<Record<string, unknown>>,
+    className: "ArangoGraphAdapter",
+    package: "arangojs",
+    installCommand: "npm install arangojs",
+  },
+};
+
+type AdapterConstructor = new (
+  graphUrl: GraphUrl,
+  credentials: GraphCredentials,
+) => GraphAdapter;
+
+export class GraphDatabase {
+  /**
+   * Parse the URL, pick the engine adapter, connect lazily.
+   *
+   * The engine driver is imported only here (first use of that engine); if it is
+   * absent the error names the package and the install command. Async because the
+   * driver import is dynamic — the connect itself still happens lazily on first
+   * operation (mirroring the relational adapters).
+   */
+  static async create(
+    url: string,
+    credentials: GraphCredentials = {},
+  ): Promise<GraphAdapter> {
+    const graphUrl = new GraphUrl(url);
+    const registration = ENGINE_ADAPTERS[graphUrl.engine];
+    if (registration === undefined) {
+      throw new GraphError(
+        `No graph adapter for engine '${graphUrl.engine}' yet (scheme '${graphUrl.scheme}'). `
+        + `Available: ${Object.keys(ENGINE_ADAPTERS).sort().join(", ")}.`,
+      );
+    }
+    let module: Record<string, unknown>;
+    try {
+      // The adapter module imports its driver at the top; a missing driver
+      // surfaces here as an actionable install error.
+      module = await registration.load();
+    } catch (cause) {
+      throw new GraphError(
+        `The graph driver for '${graphUrl.engine}' is not installed (${registration.package}). `
+        + `Install it with:\n    ${registration.installCommand}`,
+        cause,
+      );
+    }
+    const AdapterClass = module[registration.className] as AdapterConstructor | undefined;
+    if (AdapterClass === undefined) {
+      throw new GraphError(
+        `The graph adapter '${registration.className}' is missing from its module `
+        + `for engine '${graphUrl.engine}'.`,
+      );
+    }
+    return new AdapterClass(graphUrl, credentials);
+  }
+
+  /** Build from TINA4_GRAPH_URL (+ TINA4_GRAPH_USERNAME/_PASSWORD). */
+  static async fromEnv(envKey = "TINA4_GRAPH_URL"): Promise<GraphAdapter | null> {
+    const url = (process.env[envKey] ?? "").trim();
+    if (url === "") return null;
+    return GraphDatabase.create(url, {
+      username: process.env.TINA4_GRAPH_USERNAME,
+      password: process.env.TINA4_GRAPH_PASSWORD,
+    });
+  }
+}

package/packages/orm/src/graph/graphUrl.ts

@@ -0,0 +1,98 @@
+/**
+ * Graph connection URL parser — the DatabaseUrl sibling for graph engines.
+ *
+ * Parse a graph connection URL into its parts, the same way DatabaseUrl does for
+ * SQL. `engine` is the CANONICAL name the factory selects an adapter by; a scheme
+ * alias (bolt/neo4j/memgraph all speak Bolt/Cypher and share ONE adapter) resolves
+ * to its engine here. See tina4-documentation/plan/v3/features/139-graph-databases.md.
+ */
+
+/** The canonical graph engine names. */
+export type GraphEngine = "ultipa" | "bolt" | "arango";
+
+/**
+ * URL scheme to canonical engine. bolt/neo4j/memgraph share ONE adapter ("bolt");
+ * the engine label only tunes per-engine defaults. The `…s` schemes are the TLS
+ * variants.
+ */
+const SCHEME_ENGINE: Record<string, GraphEngine> = {
+  ultipa: "ultipa",
+  ultipas: "ultipa", // TLS variant
+  neo4j: "bolt",
+  "neo4j+s": "bolt",
+  bolt: "bolt",
+  "bolt+s": "bolt",
+  memgraph: "bolt",
+  arango: "arango",
+  arangodb: "arango",
+};
+
+/** Default port per engine when the URL omits one. */
+const ENGINE_DEFAULT_PORT: Record<GraphEngine, number> = {
+  ultipa: 60061,
+  bolt: 7687,
+  arango: 8529,
+};
+
+/** A parsed graph URL: engine, host, port, graph, credentials, params. */
+export class GraphUrl {
+  readonly raw: string;
+  readonly scheme: string;
+  readonly engine: GraphEngine;
+  readonly host: string;
+  readonly port: number;
+  /** The graph/database name (leading slash stripped), or null when absent. */
+  readonly graph: string | null;
+  readonly username: string | null;
+  readonly password: string | null;
+  readonly params: Record<string, string>;
+  readonly useTls: boolean;
+
+  constructor(url: string) {
+    this.raw = url;
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new Error(
+        `Unsupported graph URL '${url}' — expected scheme://[user[:password]@]host[:port]/graph `
+        + `(e.g. ultipa://host:60061/mygraph).`,
+      );
+    }
+    const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+    const engine = SCHEME_ENGINE[scheme];
+    if (engine === undefined) {
+      throw new Error(
+        `Unsupported graph URL scheme '${scheme}'. Supported: `
+        + `${Object.keys(SCHEME_ENGINE).sort().join(", ")} `
+        + `(e.g. ultipa://host:60061/mygraph).`,
+      );
+    }
+    this.scheme = scheme;
+    this.engine = engine;
+    this.host = parsed.hostname || "localhost";
+    this.port = parsed.port ? parseInt(parsed.port, 10) : ENGINE_DEFAULT_PORT[engine];
+    const path = (parsed.pathname || "").replace(/^\//, "");
+    this.graph = path === "" ? null : path;
+    this.username = parsed.username ? decodeURIComponent(parsed.username) : null;
+    this.password = parsed.password ? decodeURIComponent(parsed.password) : null;
+    this.params = {};
+    for (const [key, value] of parsed.searchParams) {
+      // First value wins, matching Python's parse_qs[0].
+      if (!(key in this.params)) this.params[key] = value;
+    }
+    // TLS if the scheme says so (…s) or ?tls=1|true.
+    this.useTls = scheme.endsWith("s") || this.params.tls === "1" || this.params.tls === "true";
+  }
+
+  /** host:port/graph — for messages, never carrying credentials. */
+  getDsn(): string {
+    const target = this.port ? `${this.host}:${this.port}` : this.host;
+    return this.graph ? `${target}/${this.graph}` : target;
+  }
+
+  static fromEnv(envKey = "TINA4_GRAPH_URL"): GraphUrl | null {
+    const url = (process.env[envKey] ?? "").trim();
+    return url === "" ? null : new GraphUrl(url);
+  }
+}