tina4-nodejs 3.13.110 → 3.13.111

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

@@ -0,0 +1,95 @@
+/**
+ * Engine-neutral graph shapes — the mirror of the relational DatabaseResult.
+ *
+ * GraphNode / GraphEdge are the portable node/edge core the unified surface
+ * returns; GraphResult is the raw-query result (records + columns), the same
+ * shape as `DatabaseResult`, so a graph read feels exactly like a SQL read.
+ * See tina4-documentation/plan/v3/decisions/ADR-0059.md and features/139.
+ */
+
+/** Engine-neutral vertex: id, labels, properties. */
+export class GraphNode {
+  readonly id: string;
+  readonly labels: string[];
+  readonly properties: Record<string, unknown>;
+
+  constructor(
+    id: string,
+    labels: string[] | null | undefined = null,
+    properties: Record<string, unknown> | null | undefined = null,
+  ) {
+    this.id = id;
+    this.labels = [...(labels ?? [])];
+    this.properties = { ...(properties ?? {}) };
+  }
+
+  toDict(): Record<string, unknown> {
+    return { id: this.id, labels: this.labels, properties: this.properties };
+  }
+}
+
+/** Engine-neutral edge: id, type, from/to node ids, properties. */
+export class GraphEdge {
+  readonly id: string;
+  readonly type: string;
+  readonly from: string;
+  readonly to: string;
+  readonly properties: Record<string, unknown>;
+
+  constructor(
+    id: string,
+    type: string,
+    from: string,
+    to: string,
+    properties: Record<string, unknown> | null | undefined = null,
+  ) {
+    this.id = id;
+    this.type = type;
+    this.from = from;
+    this.to = to;
+    this.properties = { ...(properties ?? {}) };
+  }
+
+  toDict(): Record<string, unknown> {
+    return {
+      id: this.id,
+      type: this.type,
+      from: this.from,
+      to: this.to,
+      properties: this.properties,
+    };
+  }
+}
+
+/** A raw-query result — records + columns, same shape as DatabaseResult. */
+export class GraphResult implements Iterable<Record<string, unknown>> {
+  readonly records: Record<string, unknown>[];
+  readonly columns: string[];
+
+  constructor(
+    records: Record<string, unknown>[] | null | undefined = null,
+    columns: string[] | null | undefined = null,
+  ) {
+    this.records = [...(records ?? [])];
+    this.columns = [...(columns ?? [])];
+  }
+
+  toArray(): Record<string, unknown>[] {
+    return this.records;
+  }
+
+  /** The first value of the first record, or null. */
+  scalar(): unknown {
+    if (this.records.length === 0) return null;
+    const values = Object.values(this.records[0]);
+    return values.length ? values[0] : null;
+  }
+
+  [Symbol.iterator](): Iterator<Record<string, unknown>> {
+    return this.records[Symbol.iterator]();
+  }
+
+  get length(): number {
+    return this.records.length;
+  }
+}

package/packages/orm/src/index.ts

@@ -1,115 +1,137 @@
-export type {
-  FieldType,
-  FieldDefinition,
-  ModelDefinition,
-  DatabaseAdapter,
-  DatabaseResult as DatabaseWriteResult,
-  ColumnInfo,
-  QueryOptions,
-  RelationshipDefinition,
-} from "./types.js";
-
-export { REQUIRED_ADAPTER_CAPABILITIES, NOT_REQUIRED_ON_ADAPTER } from "./types.js";
-
-export { DatabaseResult } from "./databaseResult.js";
-export type { ColumnInfoResult } from "./databaseResult.js";
-export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
-export {
-  adapterFetch, adapterQuery, adapterFetchOne, adapterExecute, adapterInsert,
-  adapterStartTransaction, adapterCommit, adapterRollback,
-  adapterTableExists, adapterTables, adapterColumns, adapterCreateTable,
-  extractLastInsertId,
-} from "./database.js";
-export type { DatabaseConfig } from "./database.js";
-export { DatabaseUrl, redactCredentials } from "./databaseUrl.js";
-export type { DatabaseEngine } from "./databaseUrl.js";
-export { discoverModels } from "./model.js";
-export type { DiscoveredModel } from "./model.js";
-export {
-  syncModels,
-  ensureMigrationTable,
-  getNextBatch,
-  isMigrationApplied,
-  recordMigration,
-  applyMigration,
-  rollback,
-  getAppliedMigrations,
-  getLastBatchMigrations,
-  removeMigrationRecord,
-  migrate,
-  createMigration,
-  status,
-  Migration,
-  splitStatements,
-  parseSetTerm,
-  normalizeQuotes,
-  sortMigrationFiles,
-  shouldSkipCreateTable,
-  shouldSkipForFirebird,
-} from "./migration.js";
-export type { MigrationResult, MigrationStatus } from "./migration.js";
-export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
-export type { AutoCrudOptions } from "./autoCrud.js";
-export { buildQuery, parseQueryString } from "./query.js";
-export { validate } from "./validation.js";
-export type { ValidationError } from "./validation.js";
-export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
-export { QueryBuilder } from "./queryBuilder.js";
-export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
-export { Point, SpatialNotSupportedError, DEFAULT_SRID } from "./point.js";
-export type { GeoJsonPoint } from "./point.js";
-export {
-  DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
-  CONNECT_TIMEOUT_TOLERANCE_MS,
-  connectTimeoutMillis,
-  driverConnectTimeoutMillis,
-  connectTarget,
-  withConnectTimeout,
-} from "./connectTimeout.js";
-export { CachedDatabaseAdapter } from "./cachedDatabase.js";
-export type { CachedAdapterOptions } from "./cachedDatabase.js";
-export { FakeData } from "./fakeData.js";
-export { seedTable, seedOrm, seedModels, autoFieldMap } from "./seeder.js";
-export type { SeedSummary, SeedOptions } from "./seeder.js";
-
-// DocStore — pymongo-style document store with a zero-config SQLite (JSON1) fallback
-export {
-  ObjectId, InvalidId, DocStoreDriverMissing, SqliteDatabase, SqliteCollection, Cursor,
-  getCollection, isServerless, resetDefaultStore, closeDocStore,
-  encodeValue, decodeValue, compileFilter,
-} from "./docstore.js";
-export type {
-  InsertOneResult, InsertManyResult, UpdateResult, DeleteResult,
-} from "./docstore.js";
-
-// Database adapters
-export { SQLiteAdapter } from "./adapters/sqlite.js";
-export { PostgresAdapter } from "./adapters/postgres.js";
-export type { PostgresConfig } from "./adapters/postgres.js";
-export { MysqlAdapter } from "./adapters/mysql.js";
-export type { MysqlConfig } from "./adapters/mysql.js";
-export { MssqlAdapter } from "./adapters/mssql.js";
-export type { MssqlConfig } from "./adapters/mssql.js";
-export { FirebirdAdapter, normalizeFirebirdDbIdentifier, resolveFirebirdCharset } from "./adapters/firebird.js";
-export type { FirebirdConfig } from "./adapters/firebird.js";
-export { MongodbAdapter } from "./adapters/mongodb.js";
-export type { MongoConfig } from "./adapters/mongodb.js";
-export { OdbcAdapter } from "./adapters/odbc.js";
-export type { OdbcConfig } from "./adapters/odbc.js";
-
-// Realtime collaboration mount (calls + chat + files) — parity with the Python master.
-export {
-  realtime,
-  iceServers,
-  type RealtimeOptions,
-  LocalStorage,
-  S3Storage,
-  selectStorage,
-  storageKey,
-  type StorageBackend,
-  Workspace as RealtimeWorkspace,
-  Channel as RealtimeChannel,
-  ChannelMember as RealtimeChannelMember,
-  Message as RealtimeMessage,
-  Attachment as RealtimeAttachment,
-} from "./realtime/index.js";
+export type {
+  FieldType,
+  FieldDefinition,
+  ModelDefinition,
+  DatabaseAdapter,
+  DatabaseResult as DatabaseWriteResult,
+  ColumnInfo,
+  QueryOptions,
+  RelationshipDefinition,
+} from "./types.js";
+
+export { REQUIRED_ADAPTER_CAPABILITIES, NOT_REQUIRED_ON_ADAPTER } from "./types.js";
+
+export { DatabaseResult } from "./databaseResult.js";
+export type { ColumnInfoResult } from "./databaseResult.js";
+export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
+export {
+  adapterFetch, adapterQuery, adapterFetchOne, adapterExecute, adapterInsert,
+  adapterStartTransaction, adapterCommit, adapterRollback,
+  adapterTableExists, adapterTables, adapterColumns, adapterCreateTable,
+  extractLastInsertId,
+} from "./database.js";
+export type { DatabaseConfig } from "./database.js";
+export { DatabaseUrl, redactCredentials } from "./databaseUrl.js";
+export type { DatabaseEngine } from "./databaseUrl.js";
+export { discoverModels } from "./model.js";
+export type { DiscoveredModel } from "./model.js";
+export {
+  syncModels,
+  ensureMigrationTable,
+  getNextBatch,
+  isMigrationApplied,
+  recordMigration,
+  applyMigration,
+  rollback,
+  getAppliedMigrations,
+  getLastBatchMigrations,
+  removeMigrationRecord,
+  migrate,
+  createMigration,
+  status,
+  Migration,
+  splitStatements,
+  parseSetTerm,
+  normalizeQuotes,
+  sortMigrationFiles,
+  shouldSkipCreateTable,
+  shouldSkipForFirebird,
+} from "./migration.js";
+export type { MigrationResult, MigrationStatus } from "./migration.js";
+export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
+export type { AutoCrudOptions } from "./autoCrud.js";
+export { buildQuery, parseQueryString } from "./query.js";
+export { validate } from "./validation.js";
+export type { ValidationError } from "./validation.js";
+export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
+export { QueryBuilder } from "./queryBuilder.js";
+export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
+export { Point, SpatialNotSupportedError, DEFAULT_SRID } from "./point.js";
+export type { GeoJsonPoint } from "./point.js";
+export {
+  DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
+  CONNECT_TIMEOUT_TOLERANCE_MS,
+  connectTimeoutMillis,
+  driverConnectTimeoutMillis,
+  connectTarget,
+  withConnectTimeout,
+} from "./connectTimeout.js";
+export { CachedDatabaseAdapter } from "./cachedDatabase.js";
+export type { CachedAdapterOptions } from "./cachedDatabase.js";
+export { FakeData } from "./fakeData.js";
+export { seedTable, seedOrm, seedModels, autoFieldMap } from "./seeder.js";
+export type { SeedSummary, SeedOptions } from "./seeder.js";
+
+// DocStore — pymongo-style document store with a zero-config SQLite (JSON1) fallback
+export {
+  ObjectId, InvalidId, DocStoreDriverMissing, SqliteDatabase, SqliteCollection, Cursor,
+  getCollection, isServerless, resetDefaultStore, closeDocStore,
+  encodeValue, decodeValue, compileFilter,
+} from "./docstore.js";
+export type {
+  InsertOneResult, InsertManyResult, UpdateResult, DeleteResult,
+} from "./docstore.js";
+
+// Database adapters
+export { SQLiteAdapter } from "./adapters/sqlite.js";
+export { PostgresAdapter } from "./adapters/postgres.js";
+export type { PostgresConfig } from "./adapters/postgres.js";
+export { MysqlAdapter } from "./adapters/mysql.js";
+export type { MysqlConfig } from "./adapters/mysql.js";
+export { MssqlAdapter } from "./adapters/mssql.js";
+export type { MssqlConfig } from "./adapters/mssql.js";
+export { FirebirdAdapter, normalizeFirebirdDbIdentifier, resolveFirebirdCharset } from "./adapters/firebird.js";
+export type { FirebirdConfig } from "./adapters/firebird.js";
+export { MongodbAdapter } from "./adapters/mongodb.js";
+export type { MongoConfig } from "./adapters/mongodb.js";
+export { OdbcAdapter } from "./adapters/odbc.js";
+export type { OdbcConfig } from "./adapters/odbc.js";
+
+// Graph data layer (Feature 139) — URL-selected graph databases, shaped like Database.
+// The engine adapters (e.g. UltipaGraphAdapter) are deliberately NOT re-exported:
+// they import their optional driver, so the factory loads them lazily and the core
+// surface below stays driver-free (the zero-dependency-core rule, ADR-0059).
+export { GraphDatabase } from "./graph/graphDatabase.js";
+export type { GraphCredentials } from "./graph/graphDatabase.js";
+export { GraphUrl } from "./graph/graphUrl.js";
+export type { GraphEngine } from "./graph/graphUrl.js";
+export { GraphNode, GraphEdge, GraphResult } from "./graph/shapes.js";
+export { GraphError, GraphConnectTimeout } from "./graph/errors.js";
+export type {
+  GraphAdapter,
+  GraphDirection,
+  NeighborOptions,
+  TraverseOptions,
+} from "./graph/graphAdapter.js";
+export {
+  resolveGraphConnectTimeout,
+  GRAPH_CONNECT_TIMEOUT_VARIABLE,
+  DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS,
+} from "./graph/connectTimeout.js";
+
+// Realtime collaboration mount (calls + chat + files) — parity with the Python master.
+export {
+  realtime,
+  iceServers,
+  type RealtimeOptions,
+  LocalStorage,
+  S3Storage,
+  selectStorage,
+  storageKey,
+  type StorageBackend,
+  Workspace as RealtimeWorkspace,
+  Channel as RealtimeChannel,
+  ChannelMember as RealtimeChannelMember,
+  Message as RealtimeMessage,
+  Attachment as RealtimeAttachment,
+} from "./realtime/index.js";

package/types/orm/src/graph/adapters/arango.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ArangoDB graph adapter — the document/AQL engine behind the same surface.
+ *
+ * Wraps the community `arangojs` npm package (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). Arango is a document store, not a labelled-
+ * property graph, so the portable core maps onto ONE vertex collection + ONE edge
+ * collection: a node's `labels` and an edge's `type` are stored as document fields,
+ * ids are Arango `_id` handles (e.g. `tina4_nodes/123`), and traversal uses AQL
+ * `FOR v IN 1..N OUTBOUND ...`. Raw query()/execute() take AQL directly.
+ *
+ * The two collections are ensured lazily on the first query (the driver's
+ * constructor is synchronous and opens no connection), mirroring the Ultipa
+ * adapter's lazy connect.
+ */
+import { GraphNode, GraphEdge, GraphResult } from "../shapes.js";
+import type { GraphUrl } from "../graphUrl.js";
+import type { GraphCredentials } from "../graphDatabase.js";
+import type { GraphAdapter, NeighborOptions, TraverseOptions } from "../graphAdapter.js";
+export declare class ArangoGraphAdapter implements GraphAdapter {
+    private readonly url;
+    private readonly db;
+    private ensured;
+    private lastError;
+    constructor(graphUrl: GraphUrl, credentials?: GraphCredentials);
+    private connectOrError;
+    private ensureCollections;
+    private aql;
+    query(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    execute(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    private nodeFromDoc;
+    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[]>;
+    close(): Promise<void>;
+    getError(): string | null;
+}

package/types/orm/src/graph/adapters/bolt.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Bolt graph adapter — Neo4j AND Memgraph (both speak Bolt + Cypher).
+ *
+ * Wraps the community `neo4j-driver` npm package (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). Neo4j and Memgraph share this ONE adapter;
+ * the URL scheme only picks the engine label and the default port.
+ *
+ * Cypher note (verified against live Neo4j + Memgraph on the lab, no mocks):
+ * `id(n)` is the portable node/edge id (an INTEGER on both — Neo4j's `elementId`
+ * is Neo4j-only, Memgraph has none); variable-length traversal is Cypher's
+ * `[*1..N]` (the OPPOSITE of Ultipa's GQL `{1,N}`); `SET n += $props` merges.
+ *
+ * The driver is configured with `disableLosslessIntegers: true`, so `id(n)` and
+ * integer properties come back as native JS numbers instead of the driver's
+ * `Integer` wrapper. Node ids are engine integers; the neutral GraphNode carries
+ * them as strings, so a Cypher `WHERE id(n) = $id` is fed `Number(id)` back.
+ */
+import { GraphNode, GraphEdge, GraphResult } from "../shapes.js";
+import type { GraphUrl } from "../graphUrl.js";
+import type { GraphCredentials } from "../graphDatabase.js";
+import type { GraphAdapter, NeighborOptions, TraverseOptions } from "../graphAdapter.js";
+export declare class BoltGraphAdapter implements GraphAdapter {
+    private readonly url;
+    private readonly database;
+    private readonly driver;
+    private lastError;
+    constructor(graphUrl: GraphUrl, credentials?: GraphCredentials);
+    private run;
+    query(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    execute(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    private nodeFromRow;
+    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[]>;
+    close(): Promise<void>;
+    getError(): string | null;
+}

package/types/orm/src/graph/adapters/ultipa.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { GraphUrl } from "../graphUrl.js";
+import type { GraphCredentials } from "../graphDatabase.js";
+import type { GraphAdapter, NeighborOptions, TraverseOptions } from "../graphAdapter.js";
+export declare class UltipaGraphAdapter implements GraphAdapter {
+    private readonly url;
+    private readonly client;
+    private lastError;
+    constructor(graphUrl: GraphUrl, credentials?: GraphCredentials);
+    private run;
+    query(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    execute(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    private nodeFromRow;
+    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[]>;
+    close(): void;
+    getError(): string | null;
+}

package/types/orm/src/graph/connectTimeout.d.ts

@@ -0,0 +1,12 @@
+/** The env var name — one spelling, so grepping finds every reader. */
+export declare const GRAPH_CONNECT_TIMEOUT_VARIABLE = "TINA4_GRAPH_CONNECT_TIMEOUT";
+/** Seconds. Long enough for a cold connect, short enough to page. */
+export declare 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 declare function resolveGraphConnectTimeout(): number | null;

package/types/orm/src/graph/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare class GraphError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * 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 declare class GraphConnectTimeout extends GraphError {
+    constructor(message: string, cause?: unknown);
+}

package/types/orm/src/graph/graphAdapter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 {
+    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[]>;
+    query(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    execute(text: string, params?: Record<string, unknown> | null): Promise<GraphResult>;
+    close(): Promise<void> | void;
+    /** Cause of the last failed operation, or null. */
+    getError(): string | null;
+}

package/types/orm/src/graph/graphDatabase.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { type GraphEngine } from "./graphUrl.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 declare const ENGINE_ADAPTERS: Partial<Record<GraphEngine, AdapterRegistration>>;
+export declare 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 create(url: string, credentials?: GraphCredentials): Promise<GraphAdapter>;
+    /** Build from TINA4_GRAPH_URL (+ TINA4_GRAPH_USERNAME/_PASSWORD). */
+    static fromEnv(envKey?: string): Promise<GraphAdapter | null>;
+}

package/types/orm/src/graph/graphUrl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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";
+/** A parsed graph URL: engine, host, port, graph, credentials, params. */
+export declare 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);
+    /** host:port/graph — for messages, never carrying credentials. */
+    getDsn(): string;
+    static fromEnv(envKey?: string): GraphUrl | null;
+}