Release v2.0.0-alpha.4

Changes since the previous version

• Implemented a new query builder pattern for RPC calls
• Fix WebSocket engine on Chrome (#436)

Full changelog

📦 Modularised packages

The repository has been restructured as a monorepo, allowing the publishing of modularised packages. This includes extracting the cbor encoding and decoding logic into a dedicated standalone @surrealdb/cbor package.

📧 Official event listeners

The original SDK allowed for the listening of events through the leaked internal surreal.emitter field. Instead, the updated SDK provides a type-safe surreal.subscribe() function allowing you to listen to events. Invoking .subscribe() now also returns a cleanup function, which unsubscribes the listener when called.

Example

// Subscribe to events
const unsub = surreal.subscribe("connected", () => {
    ...
});

// Unsubscribe
unsub();

🏹 Access internal state

Additional getters have been added to retrieve internal state from the Surreal instance, such as

• surreal.namespace and surreal.database to obtain the selected NS and DB
• surreal.params to obtain defined connection params
• surreal.accesToken and surreal.refreshToken to obtain authentication tokens

Example

await surreal.use({ namespace: surreal.namespace, database: "other-db" });

🔄 Automatic token refreshing

SurrealDB will now automatically use the provided authentication values when reconnecting and renewing access tokens. In addition, you can now also provide a callable function to resolve your authentication details on the fly, such as when loading tokens from browser storage.

Access token renewal is now also managed by default, meaning the SDK will automatically request a fresh access token using the configured authentication details once the previous token is set to expire. If necessary, you can even pass a custom renewal hook in order to customize this process.

Example

const surreal = new Surreal();

await surreal.connect("http://example.com", {
    namespace: "test",
    database: "test",
    renewAccess: true, // default true
    authentication: () => ({
        username: "foo",
        password: "bar",
    })
});

📣 Redesigned live query API

The live query functions provided by the Surreal class have been redesigned to feel more intuitive and natural to use. Additionally, live select queries can now be automatically restarted once the driver reconnects.

The record ID will now also be provided as third argument to your handlers, allowing you to determine the record when listening to patch updates.

Example

// Construct a new live subscription
const live = await surreal.live(new Table("users"));

// Listen to changes
live.subscribe((action, result, record) => {
     ...
});

// Kill the query and stop listening
live.kill();

// Create an unmanaged query from an existing id
const [id] = await surreal.query("LIVE SELECT * FROM users");
const live = await surreal.liveOf(id);

❗ Improved parameter explicitness

Query functions now no longer accept strings as table names. Instead, you must explicitly use the Table class to represent tables. This avoids situations where record ids may be accidentally passed as table names, resulting in confusing results.

Example

// tables.ts
const usersTable = new Table("users");
const productsTable = new Table("products");
...

// main.ts
await surreal.select(usersTable);

🔧 Query builder pattern

In order to provide a more transparent and ergonomic way to configure individual RPC calls, a new builder pattern has been introduced allowing the optional chaining of functions on RPC calls.

Example

// Raw queries
const [result] = await db.query("...").raw();

// Serializable results
const record = await db.select(id).jsonify();

⚙️ Separation of concerns

The SDK has been rebuilt in a way which allows for optimal code-reuse while still allowing flexibility for future RPC protocol iterations. This is done by dividing the internal SDK logic into three distinct layers.

Engines

Much like in in the original SDK, engines allow you to connect to a specific datastore, whether it be over HTTP or WS, or embedded through @surrealdb/wasm. However, this has now been streamlined further so that engines are only exclusively responsible for communicating and delivering RPC messages to a specific datastore.

Controller

The connection controller is responsible for tracking the local connection state and synchronising it with the SurrealDB instance through the instantiated engine implementation. This includes tracking the selected namespace and database, handling authentication, and performing version checks.

Surreal

Much like in the original SDK the Surreal class represents the public API and exposes all necessary public functionality, while wrapping the underlying connection controller. Each supported version of the RPC protocol receives a dedicated class (e.g. SurrealV1, SurrealV2), with the recommended version being aliases to the original Surreal export.

📚 Updated documentation

TypeScript signatures and documentations have been fixed and updated to correctly describe different arguments and overloads.

Release v2.0.0-alpha.3

📦 Modularised packages

The repository has been restructured as a monorepo, allowing the publishing of modularised packages. This includes extracting the cbor encoding and decoding logic into a dedicated standalone @surrealdb/cbor package.

📧 Official event listeners

The original SDK allowed for the listening of events through the leaked internal surreal.emitter field. Instead, the updated SDK provides a type-safe surreal.subscribe() function allowing you to listen to events. Invoking .subscribe() now also returns a cleanup function, which unsubscribes the listener when called.

Example

// Subscribe to events
const unsub = surreal.subscribe("connected", () => {
    ...
});

// Unsubscribe
unsub();

🏹 Access internal state

Additional getters have been added to retrieve internal state from the Surreal instance, such as

• surreal.namespace and surreal.database to obtain the selected NS and DB
• surreal.params to obtain defined connection params
• surreal.accesToken and surreal.refreshToken to obtain authentication tokens

Example

await surreal.use({ namespace: surreal.namespace, database: "other-db" });

🔄 Automatic token refreshing

SurrealDB will now automatically use the provided authentication values when reconnecting and renewing access tokens. In addition, you can now also provide a callable function to resolve your authentication details on the fly, such as when loading tokens from browser storage.

Access token renewal is now also managed by default, meaning the SDK will automatically request a fresh access token using the configured authentication details once the previous token is set to expire. If necessary, you can even pass a custom renewal hook in order to customize this process.

Example

const surreal = new Surreal();

await surreal.connect("http://example.com", {
    namespace: "test",
    database: "test",
    renewAccess: true, // default true
    authentication: () => ({
        username: "foo",
        password: "bar",
    })
});

📣 Redesigned live query API

The live query functions provided by the Surreal class have been redesigned to feel more intuitive and natural to use. Additionally, live select queries can now be automatically restarted once the driver reconnects.

The record ID will now also be provided as third argument to your handlers, allowing you to determine the record when listening to patch updates.

Example

// Construct a new live subscription
const live = await surreal.live(new Table("users"));

// Listen to changes
live.subscribe((action, result, record) => {
     ...
});

// Kill the query and stop listening
live.kill();

// Create an unmanaged query from an existing id
const [id] = await surreal.query("LIVE SELECT * FROM users");
const live = await surreal.liveOf(id);

❗ Improved parameter explicitness

Query functions now no longer accept strings as table names. Instead, you must explicitly use the Table class to represent tables. This avoids situations where record ids may be accidentally passed as table names, resulting in confusing results.

Example

// tables.ts
const usersTable = new Table("users");
const productsTable = new Table("products");
...

// main.ts
await surreal.select(usersTable);

⚙️ Separation of concerns

The SDK has been rebuilt in a way which allows for optimal code-reuse while still allowing flexibility for future RPC protocol iterations. This is done by dividing the internal SDK logic into three distinct layers.

Engines

Much like in in the original SDK, engines allow you to connect to a specific datastore, whether it be over HTTP or WS, or embedded through @surrealdb/wasm. However, this has now been streamlined further so that engines are only exclusively responsible for communicating and delivering RPC messages to a specific datastore.

Controller

The connection controller is responsible for tracking the local connection state and synchronising it with the SurrealDB instance through the instantiated engine implementation. This includes tracking the selected namespace and database, handling authentication, and performing version checks.

Surreal

Much like in the original SDK the Surreal class represents the public API and exposes all necessary public functionality, while wrapping the underlying connection controller. Each supported version of the RPC protocol receives a dedicated class (e.g. SurrealV1, SurrealV2), with the recommended version being aliases to the original Surreal export.

📚 Updated documentation

TypeScript signatures and documentations have been fixed and updated to correctly describe different arguments and overloads.

What's Changed

• Fix lockfile not updating by @macjuul in #430

Full Changelog: v2.0.0-alpha.2...v2.0.0-alpha.3

Release v2.0.0-alpha.2

📦 Modularised packages

The repository has been restructured as a monorepo, allowing the publishing of modularised packages. This includes extracting the cbor encoding and decoding logic into a dedicated standalone @surrealdb/cbor package.

📧 Official event listeners

The original SDK allowed for the listening of events through the leaked internal surreal.emitter field. Instead, the updated SDK provides a type-safe surreal.subscribe() function allowing you to listen to events. Invoking .subscribe() now also returns a cleanup function, which unsubscribes the listener when called.

Example

// Subscribe to events
const unsub = surreal.subscribe("connected", () => {
    ...
});

// Unsubscribe
unsub();

🏹 Access internal state

Additional getters have been added to retrieve internal state from the Surreal instance, such as

• surreal.namespace and surreal.database to obtain the selected NS and DB
• surreal.params to obtain defined connection params
• surreal.accesToken and surreal.refreshToken to obtain authentication tokens

Example

await surreal.use({ namespace: surreal.namespace, database: "other-db" });

🔄 Automatic token refreshing

SurrealDB will now automatically use the provided authentication values when reconnecting and renewing access tokens. In addition, you can now also provide a callable function to resolve your authentication details on the fly, such as when loading tokens from browser storage.

Access token renewal is now also managed by default, meaning the SDK will automatically request a fresh access token using the configured authentication details once the previous token is set to expire. If necessary, you can even pass a custom renewal hook in order to customize this process.

Example

const surreal = new Surreal();

await surreal.connect("http://example.com", {
    namespace: "test",
    database: "test",
    renewAccess: true, // default true
    authentication: () => ({
        username: "foo",
        password: "bar",
    })
});

📣 Redesigned live query API

The live query functions provided by the Surreal class have been redesigned to feel more intuitive and natural to use. Additionally, live select queries can now be automatically restarted once the driver reconnects.

The record ID will now also be provided as third argument to your handlers, allowing you to determine the record when listening to patch updates.

Example

// Construct a new live subscription
const live = await surreal.live(new Table("users"));

// Listen to changes
live.subscribe((action, result, record) => {
     ...
});

// Kill the query and stop listening
live.kill();

// Create an unmanaged query from an existing id
const [id] = await surreal.query("LIVE SELECT * FROM users");
const live = await surreal.liveOf(id);

❗ Improved parameter explicitness

Query functions now no longer accept strings as table names. Instead, you must explicitly use the Table class to represent tables. This avoids situations where record ids may be accidentally passed as table names, resulting in confusing results.

Example

// tables.ts
const usersTable = new Table("users");
const productsTable = new Table("products");
...

// main.ts
await surreal.select(usersTable);

⚙️ Separation of concerns

The SDK has been rebuilt in a way which allows for optimal code-reuse while still allowing flexibility for future RPC protocol iterations. This is done by dividing the internal SDK logic into three distinct layers.

Engines

Much like in in the original SDK, engines allow you to connect to a specific datastore, whether it be over HTTP or WS, or embedded through @surrealdb/wasm. However, this has now been streamlined further so that engines are only exclusively responsible for communicating and delivering RPC messages to a specific datastore.

Controller

The connection controller is responsible for tracking the local connection state and synchronising it with the SurrealDB instance through the instantiated engine implementation. This includes tracking the selected namespace and database, handling authentication, and performing version checks.

Surreal

Much like in the original SDK the Surreal class represents the public API and exposes all necessary public functionality, while wrapping the underlying connection controller. Each supported version of the RPC protocol receives a dedicated class (e.g. SurrealV1, SurrealV2), with the recommended version being aliases to the original Surreal export.

📚 Updated documentation

TypeScript signatures and documentations have been fixed and updated to correctly describe different arguments and overloads.

What's Changed

• Update CI and bump version by @macjuul in #426
• Update CI by @macjuul in #427
• Inline included CI job by @macjuul in #428
• Fix invalid dependency by @macjuul in #429

Full Changelog: v2.0.0-alpha.1...v2.0.0-alpha.2

Release v2.0.0-alpha.1

📦 Modularised packages

The repository has been restructured as a monorepo, allowing the publishing of modularised packages. This includes extracting the cbor encoding and decoding logic into a dedicated standalone @surrealdb/cbor package.

✉️ Official event listeners

The original SDK allowed for the listening of events through the leaked internal surreal.emitter field. Instead, the updated SDK provides a type-safe surreal.subscribe() function allowing you to listen to events. Invoking .subscribe() now also returns a cleanup function, which unsubscribes the listener when called.

Example

// Subscribe to events
const unsub = surreal.subscribe("connected", () => {
    ...
});

// Unsubscribe
unsub();

🏹 Access internal state

Additional getters have been added to retrieve internal state from the Surreal instance, such as

• surreal.namespace and surreal.database to obtain the selected NS and DB
• surreal.params to obtain defined connection params
• surreal.accesToken and surreal.refreshToken to obtain authentication tokens

Example

await surreal.use({ namespace: surreal.namespace, database: "other-db" });

🔄 Automatic token refreshing

SurrealDB will now automatically use the provided authentication values when reconnecting and renewing access tokens. In addition, you can now also provide a callable function to resolve your authentication details on the fly, such as when loading tokens from browser storage.

Access token renewal is now also managed by default, meaning the SDK will automatically request a fresh access token using the configured authentication details once the previous token is set to expire. If necessary, you can even pass a custom renewal hook in order to customize this process.

Example

const surreal = new Surreal();

await surreal.connect("http://example.com", {
    namespace: "test",
    database: "test",
    renewAccess: true, // default true
    authentication: () => ({
        username: "foo",
        password: "bar",
    })
});

📣 Redesigned live query API

The live query functions provided by the Surreal class have been redesigned to feel more intuitive and natural to use. Additionally, live select queries can now be automatically restarted once the driver reconnects.

The record ID will now also be provided as third argument to your handlers, allowing you to determine the record when listening to patch updates.

Example

// Construct a new live subscription
const live = await surreal.live(new Table("users"));

// Listen to changes
live.subscribe((action, result, record) => {
     ...
});

// Kill the query and stop listening
live.kill();

// Create an unmanaged query from an existing id
const [id] = await surreal.query("LIVE SELECT * FROM users");
const live = await surreal.liveOf(id);

❗ Improved parameter explicitness

Query functions now no longer accept strings as table names. Instead, you must explicitly use the Table class to represent tables. This avoids situations where record ids may be accidentally passed as table names, resulting in confusing results.

Example

// tables.ts
const usersTable = new Table("users");
const productsTable = new Table("products");
...

// main.ts
await surreal.select(usersTable);

⚙️ Separation of concerns

The SDK has been rebuilt in a way which allows for optimal code-reuse while still allowing flexibility for future RPC protocol iterations. This is done by dividing the internal SDK logic into three distinct layers.

Engines

Much like in in the original SDK, engines allow you to connect to a specific datastore, whether it be over HTTP or WS, or embedded through @surrealdb/wasm. However, this has now been streamlined further so that engines are only exclusively responsible for communicating and delivering RPC messages to a specific datastore.

Controller

The connection controller is responsible for tracking the local connection state and synchronising it with the SurrealDB instance through the instantiated engine implementation. This includes tracking the selected namespace and database, handling authentication, and performing version checks.

Surreal

Much like in the original SDK the Surreal class represents the public API and exposes all necessary public functionality, while wrapping the underlying connection controller. Each supported version of the RPC protocol receives a dedicated class (e.g. SurrealV1, SurrealV2), with the recommended version being aliases to the original Surreal export.

📚 Updated documentation

TypeScript signatures and documentations have been fixed and updated to correctly describe different arguments and overloads.

What's Changed

• Improve tests spawn and kill by @kearfy in #419
• SDK v2.0 by @macjuul in #420

Full Changelog: v1.3.2...v2.0.0-alpha.1

Release v1.3.2

What's Changed

• Fix range value decoding by @kearfy in #413
• Prevent prepare from locking by @macjuul in #416
• Bump version to 1.3.2 by @kearfy in #417

Full Changelog: v1.3.1...v1.3.2

Release v1.3.1

What's Changed

• Bump version to 1.3.1, add missing exports by @kearfy in #412

Full Changelog: v1.3.0...v1.3.1

v1.3.0

What's Changed

• Streamline SDK repo issue templates by @mezza29 in #404
• Automatic connection reconnecting by @macjuul in #385
• Bump version to 1.3.0 by @kearfy in #411

New Contributors

• @mezza29 made their first contribution in #404

Full Changelog: v1.2.1...v1.3.0

Release v1.2.1

What's Changed

• Fix emitter leak by @kearfy in #397
• Bump version to 1.2.1 by @kearfy in #398

Full Changelog: v1.2.0...v1.2.1

Release v1.2.0

What's Changed

• Update CONTRIBUTING.md by @Ekwuno in #390
• Make test executable configurable by @tobiemh in #391
• Fix empty ident escaping by @macjuul in #392
• Update recordid.ts by @CLoaKY233 in #393
• Expose import function by @macjuul in #394
• Bump version to 1.2.0 by @kearfy in #396

New Contributors

• @tobiemh made their first contribution in #391
• @CLoaKY233 made their first contribution in #393

Full Changelog: v1.1.0...v1.2.0

Release v1.1.0

What's Changed

• RecordId stringification fixes by @kearfy in #355
• Refactor and cleanup codebase by @macjuul in #357
• Value deep equality function by @macjuul in #358
• Update README.md by @Ekwuno in #363
• Update README links by @lkwr in #362
• Reusable gaps by @kearfy in #364
• Fix future toString by @macjuul in #365
• Add toleration for StringRecordId (#372) by @knackstedt in #373
• Add support for RecordId (#372) by @knackstedt in #374
• Add .export() by @kearfy in #378
• Cloudflare Worker fixes by @kearfy in #379
• Add back sourcemaps by @kearfy in #380
• Expose export functionality by @macjuul in #381
• Clean up the public API by @macjuul in #382
• bump version to 1.1.0 by @macjuul in #383

New Contributors

• @Ekwuno made their first contribution in #363
• @knackstedt made their first contribution in #373

Full Changelog: v1.0.6...v1.1.0