version-detector

(no submodules)

Purpose

Provides parseVersion and detectVersion for resolving the version of a running SurrealDB instance. Version detection is critical for adapting query patterns and feature availability across the supported major versions (1, 2, 3). By centralising this logic, the adapter and init subsystems can make version-conditional decisions without re-parsing the raw version string in multiple places.

parseVersion is a pure function suitable for property-based testing. detectVersion wraps the async db.version() driver call with structured error handling.

Features

Strips the "surrealdb-" prefix that the official driver prepends to version strings
Parses major.minor.patch[-prerelease] semver format
Validates that the major version is within the supported range (1–3)
Returns a typed VersionInfo object
Propagates cause-chain on query failures

Usage: Basic Example

import { parseVersion } from "@suaveplan/surrealdb/utils/version-detector";

const info = parseVersion("surrealdb-2.1.0");
// { version: "2.1.0", major: 2, minor: 1, patch: 0 }

Usage: Advanced Example

import { detectVersion } from "@suaveplan/surrealdb/utils/version-detector";
import type { SurrealClientLike } from "@suaveplan/surrealdb/types/types";

async function checkCompatibility(db: SurrealClientLike): Promise<void> {
  const info = await detectVersion(db);
  if (info.major < 2) {
    console.warn("SurrealDB v1 detected — some features are unavailable");
  }
}

API Reference

`parseVersion(raw: string): VersionInfo`

Pure function. Parses a raw version string. Throws SurrealError(VERSION_UNSUPPORTED) for unparseable strings or unsupported major versions.

Parameters:

raw — raw version string from the driver, e.g. "surrealdb-2.1.0" or "1.5.3-beta.1"

Returns: VersionInfo with version, major, minor, patch, and optional prerelease.

Throws: SurrealError(SURREAL.VERSION_UNSUPPORTED) if the string cannot be parsed or the major version is outside [1, 3].

`detectVersion(db: SurrealClientLike): Promise<VersionInfo>`

Async. Calls db.version() and delegates to parseVersion.

Throws: SurrealError(SURREAL.QUERY_FAILED) if the driver call throws.

Implementation Notes

The regex anchors to the beginning of the string after prefix stripping to handle prerelease suffixes like -beta.1 or -rc.2. The MIN_SUPPORTED_MAJOR and MAX_SUPPORTED_MAJOR constants are read from the constants/index.ts module rather than hard-coded, making the supported range easy to update when new major versions are released.

2.6 KiB Raw Blame History Unescape Escape