Add dedicated @surrealdb/sqon package & add type-safe JSON format

[macjuul]

Thank you for submitting this pull request! We appreciate you spending the time to work on these changes.

What is the motivation?

SurrealDB offers a rich type system featuring an array of first party data values such as durations, record ids, and more. While the SDK offers bi-directional encoding and decoding for CBOR, it only offers one-way encoding for JSON, while also resulting in a loss of type information.

Without proper JSON encoding/decoding support, it becomes difficult to communicate SurrealDB values across application boundaries reliably. Some examples of where this new format will help include preserving type-safety across REST APIs, storing values in an easy to debug format, and communicating data with LLMs.

What does this change do?

The over al goal of this PR is to improve the portability of SurrealDB values (So called SQON-values). This is done by extracting the existing value classes, codec logic, and certain helper values to a new @surrealdb/sqon package. This allows for the parsing and use of SQON values without requiring the presence of the entire SDK.

Additionally, a new type-safe JsonCodec has been added which makes use of a new EJSON inspired representation. The resulting structure is fully JSON compliant, and can be parsed back into SQON values.

For backwards compability, the SDK re-exports all @surrealdb/sqon exports.

Example

import { DateTime, Decimal, Duration, JsonCodec, RecordId, Uuid } from "@surrealdb/sqon";

// encoding a value

const result = JsonCodec.default.encode({
    id: new RecordId("table", Uuid.v4()),
    date: new DateTime(),
    decimal: new Decimal("123.456"),
    duration: new Duration("1h30m"),
    uuid: new Uuid("123e4567-e89b-12d3-a456-426614174000"),
});

// results in

{
  "id": {
    "$recordId": {
      "tb": "table",
      "id": {
        "$uuid": "37532d5b-775a-4208-bacd-2b4af45987e7"
      }
    }
  },
  "date": {
    "$datetime": "2026-04-07T20:08:35.801599292Z"
  },
  "decimal": {
    "$decimal": "123.456"
  },
  "duration": {
    "$duration": "1h30m"
  },
  "uuid": {
    "$uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

toJSON

The existing toJSON() implementations on value classes currently return a legacy JSON structure which does not preserve type information.

You can configure Value classes to return the new JSON format by calling the following function during initialization.

Value.useExperimentalToJson();

What is your testing strategy?

Added tests

Is this related to any issues?

• Fixes Bug: new StringRecordId("") causes the connection to be dropped. #325 by implementing an alternative serialization format, ultimately making StringRecordId obsolete in the future

Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines