Thank you for submitting this pull request! We appreciate you spending the time to work on these changes.
What is the motivation?
We've worked hard the past months to improve SurrealDB's protocol with the ability in mind to ship better developer experiences as a result. The second step in this project is to revamp the JavaScript SDK to incorporate these improvements, and to ship it!
What does this change do?
Adopted the CBOR Protocol. CBOR allows us to have an understanding of native SurrealQL values such as RecordId's, Durations, UUIDs, Dates, Decimals and Geometries.
Adopted the POST /rpc endpoint. This means that the API for WS and HTTP is guaranteed to be the same. Live query support for HTTP will be added in the future via SSE.
Introducing a new Emitter. Every Surreal instance has an Emitter which is used for async communication which cannot be handled via basic promises, such as gathering (live) responses. Additionally, we also push connecting, connected, disconnected and error messages via the emitter.
Improved error handling. Every error thrown now extends SurrealDbError, which means it's easier to check if an error comes from the surrealdb.js library. Additionally, if the server sends back an unexpected response, the client will now emit that error and close the connection, sending a disconnected error to pending requests preventing any dangling promises.
select, create, update, merge, delete, patch and insert are now inline with the RPC protocol again in sending back an object instead of an array if you pass a record id instead of a table name. This is now possible because of the RecordId support, meaning we can differenciate the resulting type of the method based on the input.
What is your testing strategy?
Tests are now all written with Deno.test. Will look into adding back tests for NodeJS and Bun in a future PR.
Is this related to any issues?
If this pull request is related to any other pull request or issue, or resolves any issues - then link all related pull requests and issues here.
Thank you for submitting this pull request! We appreciate you spending the time to work on these changes.
What is the motivation?
We've worked hard the past months to improve SurrealDB's protocol with the ability in mind to ship better developer experiences as a result. The second step in this project is to revamp the JavaScript SDK to incorporate these improvements, and to ship it!
What does this change do?
POST /rpcendpoint. This means that the API for WS and HTTP is guaranteed to be the same. Live query support for HTTP will be added in the future via SSE.Surrealinstance has anEmitterwhich is used for async communication which cannot be handled via basic promises, such as gathering (live) responses. Additionally, we also pushconnecting,connected,disconnectedanderrormessages via the emitter.SurrealDbError, which means it's easier to check if an error comes from the surrealdb.js library. Additionally, if the server sends back an unexpected response, the client will now emit that error and close the connection, sending a disconnected error to pending requests preventing any dangling promises.select,create,update,merge,delete,patchandinsertare now inline with the RPC protocol again in sending back an object instead of an array if you pass a record id instead of a table name. This is now possible because of theRecordIdsupport, meaning we can differenciate the resulting type of the method based on the input.What is your testing strategy?
Tests are now all written with
Deno.test. Will look into adding back tests for NodeJS and Bun in a future PR.Is this related to any issues?
If this pull request is related to any other pull request or issue, or resolves any issues - then link all related pull requests and issues here.
Have you read the Contributing Guidelines?