tina4-nodejs 3.13.110 → 3.13.111

package/packages/orm/dist/index.js

@@ -42620,6 +42620,775 @@ var init_docstore = __esm({
   }
 });
 
+// src/graph/graphUrl.ts
+var SCHEME_ENGINE, ENGINE_DEFAULT_PORT, GraphUrl;
+var init_graphUrl = __esm({
+  "src/graph/graphUrl.ts"() {
+    "use strict";
+    SCHEME_ENGINE = {
+      ultipa: "ultipa",
+      ultipas: "ultipa",
+      // TLS variant
+      neo4j: "bolt",
+      "neo4j+s": "bolt",
+      bolt: "bolt",
+      "bolt+s": "bolt",
+      memgraph: "bolt",
+      arango: "arango",
+      arangodb: "arango"
+    };
+    ENGINE_DEFAULT_PORT = {
+      ultipa: 60061,
+      bolt: 7687,
+      arango: 8529
+    };
+    GraphUrl = class _GraphUrl {
+      raw;
+      scheme;
+      engine;
+      host;
+      port;
+      /** The graph/database name (leading slash stripped), or null when absent. */
+      graph;
+      username;
+      password;
+      params;
+      useTls;
+      constructor(url) {
+        this.raw = url;
+        let parsed;
+        try {
+          parsed = new URL(url);
+        } catch {
+          throw new Error(
+            `Unsupported graph URL '${url}' \u2014 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 === void 0) {
+          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 path8 = (parsed.pathname || "").replace(/^\//, "");
+        this.graph = path8 === "" ? null : path8;
+        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) {
+          if (!(key in this.params)) this.params[key] = value;
+        }
+        this.useTls = scheme.endsWith("s") || this.params.tls === "1" || this.params.tls === "true";
+      }
+      /** host:port/graph — for messages, never carrying credentials. */
+      getDsn() {
+        const target = this.port ? `${this.host}:${this.port}` : this.host;
+        return this.graph ? `${target}/${this.graph}` : target;
+      }
+      static fromEnv(envKey = "TINA4_GRAPH_URL") {
+        const url = (process.env[envKey] ?? "").trim();
+        return url === "" ? null : new _GraphUrl(url);
+      }
+    };
+  }
+});
+
+// src/graph/errors.ts
+var GraphError, GraphConnectTimeout;
+var init_errors = __esm({
+  "src/graph/errors.ts"() {
+    "use strict";
+    GraphError = class extends Error {
+      constructor(message, cause) {
+        super(message, cause === void 0 ? void 0 : { cause });
+        this.name = "GraphError";
+      }
+    };
+    GraphConnectTimeout = class extends GraphError {
+      constructor(message, cause) {
+        super(message, cause);
+        this.name = "GraphConnectTimeout";
+      }
+    };
+  }
+});
+
+// src/graph/shapes.ts
+var GraphNode, GraphEdge, GraphResult;
+var init_shapes = __esm({
+  "src/graph/shapes.ts"() {
+    "use strict";
+    GraphNode = class {
+      id;
+      labels;
+      properties;
+      constructor(id, labels = null, properties = null) {
+        this.id = id;
+        this.labels = [...labels ?? []];
+        this.properties = { ...properties ?? {} };
+      }
+      toDict() {
+        return { id: this.id, labels: this.labels, properties: this.properties };
+      }
+    };
+    GraphEdge = class {
+      id;
+      type;
+      from;
+      to;
+      properties;
+      constructor(id, type2, from, to, properties = null) {
+        this.id = id;
+        this.type = type2;
+        this.from = from;
+        this.to = to;
+        this.properties = { ...properties ?? {} };
+      }
+      toDict() {
+        return {
+          id: this.id,
+          type: this.type,
+          from: this.from,
+          to: this.to,
+          properties: this.properties
+        };
+      }
+    };
+    GraphResult = class {
+      records;
+      columns;
+      constructor(records = null, columns = null) {
+        this.records = [...records ?? []];
+        this.columns = [...columns ?? []];
+      }
+      toArray() {
+        return this.records;
+      }
+      /** The first value of the first record, or null. */
+      scalar() {
+        if (this.records.length === 0) return null;
+        const values = Object.values(this.records[0]);
+        return values.length ? values[0] : null;
+      }
+      [Symbol.iterator]() {
+        return this.records[Symbol.iterator]();
+      }
+      get length() {
+        return this.records.length;
+      }
+    };
+  }
+});
+
+// src/graph/connectTimeout.ts
+function resolveGraphConnectTimeout() {
+  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 \u2014 bounding graph connects at the ${DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS}s default instead`
+    );
+    return DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS;
+  }
+  return seconds <= 0 ? null : seconds;
+}
+var GRAPH_CONNECT_TIMEOUT_VARIABLE, DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS;
+var init_connectTimeout2 = __esm({
+  "src/graph/connectTimeout.ts"() {
+    "use strict";
+    init_src2();
+    GRAPH_CONNECT_TIMEOUT_VARIABLE = "TINA4_GRAPH_CONNECT_TIMEOUT";
+    DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS = 10;
+  }
+});
+
+// src/graph/adapters/ultipa.ts
+var ultipa_exports = {};
+__export(ultipa_exports, {
+  UltipaGraphAdapter: () => UltipaGraphAdapter
+});
+function propClause(properties) {
+  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 = {};
+  for (const key of keys) params[`p_${key}`] = props[key];
+  return { clause: `{${pairs}}`, params };
+}
+function errorMessage(exc) {
+  if (exc instanceof Error) return exc.message;
+  return String(exc);
+}
+var DRIVER_PACKAGE2, driver, UltipaClient, UltipaConnectError, UNBOUNDED_CONNECT_SECONDS, UltipaGraphAdapter;
+var init_ultipa = __esm({
+  async "src/graph/adapters/ultipa.ts"() {
+    "use strict";
+    init_shapes();
+    init_errors();
+    init_connectTimeout2();
+    DRIVER_PACKAGE2 = "tina4-ultipa";
+    driver = await import(DRIVER_PACKAGE2);
+    UltipaClient = driver.UltipaClient;
+    UltipaConnectError = driver.UltipaConnectError;
+    UNBOUNDED_CONNECT_SECONDS = 31536e4;
+    UltipaGraphAdapter = class {
+      url;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      client;
+      lastError = null;
+      constructor(graphUrl, credentials = {}) {
+        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 -------------------------------------
+      async run(gql, params = null, readOnly = true) {
+        try {
+          await this.client.connect();
+        } catch (exc) {
+          this.lastError = errorMessage(exc);
+          if (exc instanceof UltipaConnectError || exc?.name === "UltipaConnectError") {
+            const elapsed = typeof exc?.elapsed === "number" ? exc.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
+            );
+          }
+          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, params = null) {
+        const result = await this.run(text, params, true);
+        return new GraphResult(result.dicts(), result.columns);
+      }
+      async execute(text, params = null) {
+        const result = await this.run(text, params, false);
+        return new GraphResult(result.dicts(), result.columns);
+      }
+      // -- portable node/edge/traverse core (GQL) ----------------------------
+      nodeFromRow(row) {
+        if (row === null || row === void 0) return null;
+        return new GraphNode(
+          String(row.id),
+          row.labels ?? [],
+          row.props ?? {}
+        );
+      }
+      async addNode(label, properties = 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();
+        return rows.length ? this.nodeFromRow(rows[0]) : null;
+      }
+      async addEdge(fromId, toId, type2, properties = null) {
+        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:\`${type2}\` ${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();
+        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 ?? {}
+        );
+      }
+      async getNode(nodeId) {
+        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();
+        return rows.length ? this.nodeFromRow(rows[0]) : null;
+      }
+      async updateNode(nodeId, properties) {
+        const props = properties ?? {};
+        const keys = Object.keys(props);
+        const sets = keys.map((key) => `n.${key} = $p_${key}`).join(", ");
+        const params = { 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();
+        return rows.length ? this.nodeFromRow(rows[0]) : null;
+      }
+      async deleteNode(nodeId) {
+        const gql = "MATCH (n) WHERE id(n) = $id DETACH DELETE n";
+        await this.run(gql, { id: nodeId }, false);
+        return true;
+      }
+      async neighbors(nodeId, options = {}) {
+        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();
+        return rows.map((row) => this.nodeFromRow(row)).filter((node) => node !== null);
+      }
+      async traverse(startId, options = {}) {
+        const depth = options.depth ?? 1;
+        const direction = options.direction ?? "both";
+        const limit = options.limit ?? 1e3;
+        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();
+        return rows.map((row) => this.nodeFromRow(row)).filter((node) => node !== null);
+      }
+      close() {
+        this.client.close();
+      }
+      getError() {
+        return this.lastError;
+      }
+    };
+  }
+});
+
+// src/graph/adapters/bolt.ts
+var bolt_exports = {};
+__export(bolt_exports, {
+  BoltGraphAdapter: () => BoltGraphAdapter
+});
+function errorMessage2(exc) {
+  if (exc instanceof Error) return exc.message;
+  return String(exc);
+}
+function boltId(id) {
+  const value = Number(id);
+  return Number.isNaN(value) ? -1 : value;
+}
+var DRIVER_PACKAGE3, driverModule, neo4j, BoltGraphAdapter;
+var init_bolt = __esm({
+  async "src/graph/adapters/bolt.ts"() {
+    "use strict";
+    init_shapes();
+    init_errors();
+    init_connectTimeout2();
+    DRIVER_PACKAGE3 = "neo4j-driver";
+    driverModule = await import(DRIVER_PACKAGE3);
+    neo4j = driverModule.default ?? driverModule;
+    BoltGraphAdapter = class {
+      url;
+      database;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      driver;
+      lastError = null;
+      constructor(graphUrl, credentials = {}) {
+        this.url = graphUrl;
+        this.database = graphUrl.graph || null;
+        const user = graphUrl.username || credentials.username || "neo4j";
+        const pwd = graphUrl.password || credentials.password || "";
+        const scheme = graphUrl.useTls ? "bolt+s" : "bolt";
+        const uri = `${scheme}://${graphUrl.host}:${graphUrl.port}`;
+        const timeout = resolveGraphConnectTimeout();
+        const config = { disableLosslessIntegers: true };
+        if (timeout !== null) {
+          const ms = Math.max(1, Math.ceil(timeout * 1e3));
+          config.connectionTimeout = ms;
+          config.connectionAcquisitionTimeout = ms;
+          config.maxTransactionRetryTime = ms;
+        }
+        this.driver = neo4j.driver(uri, neo4j.auth.basic(user, pwd), config);
+      }
+      // -- connection + raw pass-through -------------------------------------
+      async run(cypher, params = null) {
+        const session = this.database ? this.driver.session({ database: this.database }) : this.driver.session();
+        try {
+          const result = await session.run(cypher, params ?? {});
+          return result.records.map((record) => record.toObject());
+        } catch (exc) {
+          this.lastError = errorMessage2(exc);
+          const code = exc?.code ?? "";
+          const message = this.lastError.toLowerCase();
+          if (code === "ServiceUnavailable" || code === neo4j.error?.SERVICE_UNAVAILABLE || message.includes("timed out") || message.includes("timeout")) {
+            throw new GraphConnectTimeout(
+              `Graph connect to ${this.url.host}:${this.url.port} timed out (${GRAPH_CONNECT_TIMEOUT_VARIABLE}). Raise ${GRAPH_CONNECT_TIMEOUT_VARIABLE} if the server is simply slow, or set it to 0 to wait indefinitely.`,
+              exc
+            );
+          }
+          throw new GraphError(this.lastError, exc);
+        } finally {
+          await session.close();
+        }
+      }
+      async query(text, params = null) {
+        const rows = await this.run(text, params);
+        const columns = rows.length ? Object.keys(rows[0]) : [];
+        return new GraphResult(rows, columns);
+      }
+      async execute(text, params = null) {
+        return this.query(text, params);
+      }
+      // -- portable node/edge/traverse core (Cypher) -------------------------
+      nodeFromRow(row) {
+        if (row === null || row === void 0) return null;
+        return new GraphNode(
+          String(row.id),
+          row.labels ?? [],
+          row.props ?? {}
+        );
+      }
+      async addNode(label, properties = null) {
+        const cypher = `CREATE (n:\`${label}\` $props) RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props`;
+        const rows = await this.run(cypher, { props: properties ?? {} });
+        return rows.length ? this.nodeFromRow(rows[0]) : null;
+      }
+      async addEdge(fromId, toId, type2, properties = null) {
+        const cypher = `MATCH (a), (b) WHERE id(a) = $from_id AND id(b) = $to_id CREATE (a)-[e:\`${type2}\` $props]->(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(cypher, {
+          from_id: boltId(fromId),
+          to_id: boltId(toId),
+          props: properties ?? {}
+        });
+        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 ?? {}
+        );
+      }
+      async getNode(nodeId) {
+        const cypher = `MATCH (n) WHERE id(n) = $id RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props`;
+        const rows = await this.run(cypher, { id: boltId(nodeId) });
+        return rows.length ? this.nodeFromRow(rows[0]) : null;
+      }
+      async updateNode(nodeId, properties) {
+        const cypher = `MATCH (n) WHERE id(n) = $id SET n += $props RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props`;
+        const rows = await this.run(cypher, { id: boltId(nodeId), props: properties ?? {} });
+        return rows.length ? this.nodeFromRow(rows[0]) : null;
+      }
+      async deleteNode(nodeId) {
+        await this.run("MATCH (n) WHERE id(n) = $id DETACH DELETE n", { id: boltId(nodeId) });
+        return true;
+      }
+      async neighbors(nodeId, options = {}) {
+        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 cypher = `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(cypher, { id: boltId(nodeId) });
+        return rows.map((row) => this.nodeFromRow(row)).filter((node) => node !== null);
+      }
+      async traverse(startId, options = {}) {
+        const depth = options.depth ?? 1;
+        const direction = options.direction ?? "both";
+        const limit = options.limit ?? 1e3;
+        const edge = options.edgeType ? `:\`${options.edgeType}\`` : "";
+        const range = `*1..${Math.trunc(depth)}`;
+        const arrow = {
+          out: `-[${edge}${range}]->`,
+          in: `<-[${edge}${range}]-`,
+          both: `-[${edge}${range}]-`
+        }[direction];
+        const cypher = `MATCH (n)${arrow}(m) 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(cypher, { start: boltId(startId) });
+        return rows.map((row) => this.nodeFromRow(row)).filter((node) => node !== null);
+      }
+      async close() {
+        await this.driver.close();
+      }
+      getError() {
+        return this.lastError;
+      }
+    };
+  }
+});
+
+// src/graph/adapters/arango.ts
+var arango_exports = {};
+__export(arango_exports, {
+  ArangoGraphAdapter: () => ArangoGraphAdapter
+});
+function cleanProps(doc) {
+  const props = {};
+  for (const [key, value] of Object.entries(doc)) {
+    if (!RESERVED.has(key)) props[key] = value;
+  }
+  return props;
+}
+function errorMessage3(exc) {
+  if (exc instanceof Error) return exc.message;
+  return String(exc);
+}
+var DRIVER_PACKAGE4, driverModule2, ArangoDatabase, VERTEX_COLLECTION, EDGE_COLLECTION, RESERVED, ArangoGraphAdapter;
+var init_arango = __esm({
+  async "src/graph/adapters/arango.ts"() {
+    "use strict";
+    init_shapes();
+    init_errors();
+    init_connectTimeout2();
+    DRIVER_PACKAGE4 = "arangojs";
+    driverModule2 = await import(DRIVER_PACKAGE4);
+    ArangoDatabase = driverModule2.Database ?? driverModule2.default?.Database;
+    VERTEX_COLLECTION = "tina4_nodes";
+    EDGE_COLLECTION = "tina4_edges";
+    RESERVED = /* @__PURE__ */ new Set(["_id", "_key", "_rev", "_from", "_to", "_labels", "_type"]);
+    ArangoGraphAdapter = class {
+      url;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      db;
+      ensured = false;
+      lastError = null;
+      constructor(graphUrl, credentials = {}) {
+        this.url = graphUrl;
+        const scheme = graphUrl.useTls ? "https" : "http";
+        const user = graphUrl.username || credentials.username || "root";
+        const pwd = graphUrl.password || credentials.password || "";
+        const database = graphUrl.graph || "_system";
+        const timeout = resolveGraphConnectTimeout();
+        const config = {
+          url: `${scheme}://${graphUrl.host}:${graphUrl.port}`,
+          databaseName: database,
+          auth: { username: user, password: pwd }
+        };
+        if (timeout !== null) config.timeout = Math.max(1, Math.ceil(timeout * 1e3));
+        this.db = new ArangoDatabase(config);
+      }
+      connectOrError(exc) {
+        const text = errorMessage3(exc).toLowerCase();
+        if (text.includes("timed out") || text.includes("timeout") || text.includes("connection") || text.includes("econnrefused") || text.includes("etimedout") || text.includes("max retries")) {
+          return new GraphConnectTimeout(
+            `Graph connect to ${this.url.host}:${this.url.port} timed out (${GRAPH_CONNECT_TIMEOUT_VARIABLE}). Raise ${GRAPH_CONNECT_TIMEOUT_VARIABLE} if the server is simply slow, or set it to 0 to wait indefinitely.`,
+            exc
+          );
+        }
+        return new GraphError(errorMessage3(exc), exc);
+      }
+      async ensureCollections() {
+        if (this.ensured) return;
+        try {
+          const nodes = this.db.collection(VERTEX_COLLECTION);
+          if (!await nodes.exists()) await this.db.createCollection(VERTEX_COLLECTION);
+          const edges = this.db.collection(EDGE_COLLECTION);
+          if (!await edges.exists()) await this.db.createEdgeCollection(EDGE_COLLECTION);
+          this.ensured = true;
+        } catch (exc) {
+          this.lastError = errorMessage3(exc);
+          throw this.connectOrError(exc);
+        }
+      }
+      async aql(query, bind2 = null) {
+        await this.ensureCollections();
+        try {
+          const cursor = await this.db.query({ query, bindVars: bind2 ?? {} });
+          return await cursor.all();
+        } catch (exc) {
+          this.lastError = errorMessage3(exc);
+          throw this.connectOrError(exc);
+        }
+      }
+      async query(text, params = null) {
+        const rows = await this.aql(text, params);
+        const first = rows[0];
+        const columns = rows.length && first && typeof first === "object" ? Object.keys(first) : [];
+        return new GraphResult(rows, columns);
+      }
+      async execute(text, params = null) {
+        return this.query(text, params);
+      }
+      // -- portable node/edge/traverse core (AQL) ----------------------------
+      nodeFromDoc(doc) {
+        if (doc === null || doc === void 0) return null;
+        return new GraphNode(
+          String(doc._id),
+          doc._labels ?? [],
+          cleanProps(doc)
+        );
+      }
+      async addNode(label, properties = null) {
+        const doc = { ...properties ?? {}, _labels: [label] };
+        const rows = await this.aql(`INSERT @doc INTO ${VERTEX_COLLECTION} RETURN NEW`, { doc });
+        return rows.length ? this.nodeFromDoc(rows[0]) : null;
+      }
+      async addEdge(fromId, toId, type2, properties = null) {
+        const doc = { ...properties ?? {}, _from: fromId, _to: toId, _type: type2 };
+        const rows = await this.aql(`INSERT @doc INTO ${EDGE_COLLECTION} RETURN NEW`, { doc });
+        if (rows.length === 0) return null;
+        const row = rows[0];
+        return new GraphEdge(
+          String(row._id),
+          String(row._type),
+          String(row._from),
+          String(row._to),
+          cleanProps(row)
+        );
+      }
+      async getNode(nodeId) {
+        const rows = await this.aql("RETURN DOCUMENT(@id)", { id: nodeId });
+        return rows.length && rows[0] ? this.nodeFromDoc(rows[0]) : null;
+      }
+      async updateNode(nodeId, properties) {
+        const rows = await this.aql(
+          `UPDATE PARSE_IDENTIFIER(@id).key WITH @props IN ${VERTEX_COLLECTION} RETURN NEW`,
+          { id: nodeId, props: properties ?? {} }
+        );
+        return rows.length ? this.nodeFromDoc(rows[0]) : null;
+      }
+      async deleteNode(nodeId) {
+        await this.aql(
+          `FOR e IN ${EDGE_COLLECTION} FILTER e._from == @id OR e._to == @id REMOVE e IN ${EDGE_COLLECTION}`,
+          { id: nodeId }
+        );
+        await this.aql(
+          `REMOVE PARSE_IDENTIFIER(@id).key IN ${VERTEX_COLLECTION}`,
+          { id: nodeId }
+        );
+        return true;
+      }
+      async neighbors(nodeId, options = {}) {
+        const direction = options.direction ?? "both";
+        const limit = options.limit ?? 100;
+        const arangoDir = { out: "OUTBOUND", in: "INBOUND", both: "ANY" }[direction];
+        const typeFilter = options.edgeType ? "FILTER e._type == @etype " : "";
+        const bind2 = { start: nodeId, limit: Math.trunc(limit) };
+        if (options.edgeType) bind2.etype = options.edgeType;
+        const rows = await this.aql(
+          `FOR v, e IN 1..1 ${arangoDir} @start ${EDGE_COLLECTION} ${typeFilter}LIMIT @limit RETURN DISTINCT v`,
+          bind2
+        );
+        return rows.map((doc) => this.nodeFromDoc(doc)).filter((node) => node !== null);
+      }
+      async traverse(startId, options = {}) {
+        const depth = options.depth ?? 1;
+        const direction = options.direction ?? "both";
+        const limit = options.limit ?? 1e3;
+        const arangoDir = { out: "OUTBOUND", in: "INBOUND", both: "ANY" }[direction];
+        const typeFilter = options.edgeType ? "FILTER e._type == @etype " : "";
+        const bind2 = { start: startId, limit: Math.trunc(limit) };
+        if (options.edgeType) bind2.etype = options.edgeType;
+        const rows = await this.aql(
+          `FOR v, e IN 1..${Math.trunc(depth)} ${arangoDir} @start ${EDGE_COLLECTION} ${typeFilter}LIMIT @limit RETURN DISTINCT v`,
+          bind2
+        );
+        return rows.map((doc) => this.nodeFromDoc(doc)).filter((node) => node !== null);
+      }
+      async close() {
+        if (typeof this.db.close === "function") this.db.close();
+      }
+      getError() {
+        return this.lastError;
+      }
+    };
+  }
+});
+
+// src/graph/graphDatabase.ts
+var ENGINE_ADAPTERS, GraphDatabase;
+var init_graphDatabase = __esm({
+  "src/graph/graphDatabase.ts"() {
+    "use strict";
+    init_graphUrl();
+    init_errors();
+    ENGINE_ADAPTERS = {
+      ultipa: {
+        load: () => init_ultipa().then(() => ultipa_exports),
+        className: "UltipaGraphAdapter",
+        package: "tina4-ultipa",
+        installCommand: "npm install tina4-ultipa"
+      },
+      bolt: {
+        // Neo4j AND Memgraph — both speak Bolt/Cypher over the neo4j-driver package.
+        load: () => init_bolt().then(() => bolt_exports),
+        className: "BoltGraphAdapter",
+        package: "neo4j-driver",
+        installCommand: "npm install neo4j-driver"
+      },
+      arango: {
+        load: () => init_arango().then(() => arango_exports),
+        className: "ArangoGraphAdapter",
+        package: "arangojs",
+        installCommand: "npm install arangojs"
+      }
+    };
+    GraphDatabase = 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, credentials = {}) {
+        const graphUrl = new GraphUrl(url);
+        const registration = ENGINE_ADAPTERS[graphUrl.engine];
+        if (registration === void 0) {
+          throw new GraphError(
+            `No graph adapter for engine '${graphUrl.engine}' yet (scheme '${graphUrl.scheme}'). Available: ${Object.keys(ENGINE_ADAPTERS).sort().join(", ")}.`
+          );
+        }
+        let module;
+        try {
+          module = await registration.load();
+        } catch (cause) {
+          throw new GraphError(
+            `The graph driver for '${graphUrl.engine}' is not installed (${registration.package}). Install it with:
+    ${registration.installCommand}`,
+            cause
+          );
+        }
+        const AdapterClass = module[registration.className];
+        if (AdapterClass === void 0) {
+          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") {
+        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
+        });
+      }
+    };
+  }
+});
+
 // src/realtime/models/workspace.ts
 var Workspace;
 var init_workspace = __esm({
@@ -43178,6 +43947,7 @@ __export(index_exports, {
   CachedDatabaseAdapter: () => CachedDatabaseAdapter,
   Cursor: () => Cursor,
   DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS: () => DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
+  DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS: () => DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS,
   DEFAULT_SRID: () => DEFAULT_SRID,
   Database: () => Database,
   DatabaseResult: () => DatabaseResult,
@@ -43185,6 +43955,14 @@ __export(index_exports, {
   DocStoreDriverMissing: () => DocStoreDriverMissing,
   FakeData: () => FakeData2,
   FirebirdAdapter: () => FirebirdAdapter,
+  GRAPH_CONNECT_TIMEOUT_VARIABLE: () => GRAPH_CONNECT_TIMEOUT_VARIABLE,
+  GraphConnectTimeout: () => GraphConnectTimeout,
+  GraphDatabase: () => GraphDatabase,
+  GraphEdge: () => GraphEdge,
+  GraphError: () => GraphError,
+  GraphNode: () => GraphNode,
+  GraphResult: () => GraphResult,
+  GraphUrl: () => GraphUrl,
   InvalidId: () => InvalidId,
   LocalStorage: () => LocalStorage,
   Migration: () => Migration,
@@ -43266,6 +44044,7 @@ __export(index_exports, {
   resetRequestCaches: () => resetRequestCaches2,
   resolveDbPool: () => resolveDbPool,
   resolveFirebirdCharset: () => resolveFirebirdCharset,
+  resolveGraphConnectTimeout: () => resolveGraphConnectTimeout,
   rollback: () => rollback,
   seedModels: () => seedModels,
   seedOrm: () => seedOrm,
@@ -43314,6 +44093,11 @@ var init_index = __esm({
     init_firebird();
     init_mongodb();
     init_odbc();
+    init_graphDatabase();
+    init_graphUrl();
+    init_shapes();
+    init_errors();
+    init_connectTimeout2();
     init_realtime2();
   }
 });
@@ -43325,6 +44109,7 @@ export {
   CachedDatabaseAdapter,
   Cursor,
   DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
+  DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS,
   DEFAULT_SRID,
   Database,
   DatabaseResult,
@@ -43332,6 +44117,14 @@ export {
   DocStoreDriverMissing,
   FakeData2 as FakeData,
   FirebirdAdapter,
+  GRAPH_CONNECT_TIMEOUT_VARIABLE,
+  GraphConnectTimeout,
+  GraphDatabase,
+  GraphEdge,
+  GraphError,
+  GraphNode,
+  GraphResult,
+  GraphUrl,
   InvalidId,
   LocalStorage,
   Migration,
@@ -43413,6 +44206,7 @@ export {
   resetRequestCaches2 as resetRequestCaches,
   resolveDbPool,
   resolveFirebirdCharset,
+  resolveGraphConnectTimeout,
   rollback,
   seedModels,
   seedOrm,