first commit

docs/persistence/database/surrealdb/src/utils/version-detector.md

@@ -0,0 +1,65 @@
+# version-detector
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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
+
+```ts
+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
+
+```ts
+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.