surrealdb.js

SurrealDB SDK for JavaScript

APACHE-2.0 License

Downloads
15.5K
Stars
294
Committers
25
View Code on GitHub Visit Website View on X
Ecosystems: Deno, JavaScript

Bot releases are hidden (Show)

surrealdb.js - Release v0.7.2

Published by kearfy over 1 year ago

Doing a minor bugfix release to unblock some people, there will be more changes but not yet finalized

Overview of changes

  • No need to pass a URL to the constructor function of the Surreal class anymore. It's optional which allows you to initialize later with the .connect() function
  • Adding a dependency on the URL class broke the library for react-native. Whilst we don't officially support hermes, be dropped this behaviour for a custom URL parser
  • Replace isomorphic-ws with unws. Issues arrised with nextjs server components importing the isomorphic-ws package, which has some fundamental problems and is not maintained.
  • The output handler did not properly handle an empty response when querying a non-existent key. Now returns undefined.

What's Changed

New Contributors

Full Changelog: https://github.com/surrealdb/surrealdb.js/compare/v0.7.1...v0.7.2

surrealdb.js - Release v0.7.1

Published by kearfy over 1 year ago

This is a continuation of Release v0.7.0. Please read the release notes there!

What's Changed

Full Changelog: https://github.com/surrealdb/surrealdb.js/compare/0.7.0...v0.7.1

surrealdb.js - Release v0.7.0

Published by kearfy over 1 year ago

Overview of changes

  • Breaking: The typing for the .query() function has changed.
  • Maybe breaking: Client drivers in the JS library contain a new prepare function. This can be passed through an object that replaces the earlier token option (second argument of the Surreal constructor).
  • Maybe breaking: the static .singleton property has been removed, as this does not belong in the client library. The goal of the official SurrealDB drivers is merely to implement protocols provided by the code product.
  • Library has been majorly refactored. The code and possibly thrown errors should now be much easier to read and understand.
  • A basic and experimental implementation for the HTTP REST api has been started.
  • Process of testing was generally improved.

Typing for .query() function

We changed the typing for the .query() function in the previous release, but it is incorrect, as it it possible to execute multiple queries at once. We reverted back this change, with the difference being that everything is automatically mapped to the Result type.

If your typing looks like either of the following:
v0.5.0

surreal.query<Result<{
    id: string;
    field: string;
}>>("SELECT * FROM demo");

v0.6.0

surreal.query<{
    id: string;
    field: string;
}>("SELECT * FROM demo");

New types

You will have to drop the Result type (v0.5.0), or contain the type in an array (v0.6.0) like this:

surreal.query<[
  {
      id: string;
      field: string;
  }
]>("SELECT * FROM demo");

Because the types are contained in an array, you can properly type multiple queries again:

surreal.query<[
  {
      id: string;
      field: string;
  },
  {
      count: number;
  }
]>("SELECT * FROM demo; SELECT count() FROM demo GROUP ALL;");

Prepare function

The magic of the (optional) prepare function, is that it will let any data manipulation functions (.query(), .select(), etc) wait for it to finish. That may does not sound to trivial, because "I can just run .use() and authentication before I run those functions", but when it comes to frameworks like React this slightly more difficult to do, and the prepare function is a perfect fit.

import { Surreal } from 'surrealdb.js';

const surreal = new Surreal("wss://instance.domain.com", {
    prepare: async (db) => {
        await db.use('namespace', 'database');
        
        const token = localStorage.getItem('usertoken');
        if (token) {
            await db.authenticate(token);
        }
    }
});

// We do not await the connection to establish or anything.
// Instead, we can just start querying right away and it will nicely wait 
// for the intialization & prepare function to finish doing their thing!
const result = await surreal.select("something");

The prepare function is available for both the WS and (experimental) HTTP protocol!

HTTP strategy (experimental)

import { ExperimentalSurrealHTTP } from 'surrealdb.js';

const surreal = new ExperimentalSurrealHTTP('https://instance.domain.com');
const result = await surreal.query<[Something[]]>("SELECT * FROM something");

// First query, maybe result (could also be an error), first record, property "key"
// Type id: "number | undefined"   --   also undefined because the .result? might be undefined
const bla = result[0].result?.[0].key; 

type Something = {
    id: `something:${string}`;
    key: number;
};

Using node.js older than node18?

Make sure to pass on a fetch function from for example node-fetch:

import { ExperimentalSurrealHTTP } from 'surrealdb.js';
import fetch from 'node-fetch';

const surreal = new ExperimentalSurrealHTTP('https://instance.domain.com', {
    fetch
});

Where did the code for Live Queries go??

The code for Live Queries was based on the implementation of the go version of SurrealDB. It is currently not yet ready, will add it back once it's merged to main in a functioning sense. (Git is nice, I can look back to the future 😛)

What's Changed

Full Changelog: https://github.com/surrealdb/surrealdb.js/compare/v0.6.0...0.7.0

surrealdb.js - Release v0.6.0

Published by kearfy over 1 year ago

Overview of changes

  • Breaking: The typing for the .query() function has changed.
  • Typing for .select(), .update(), .change() and .modify() functions now properly return a single item if you select a single thing (user:tobie vs user).
  • The surrealdb.js library is now compatible with the beta-9 release of SurrealDB.
  • The .signup() function now only accepts ScopeAuth (a user cannot signup for a root, namespace or database account).
  • There now also is a named export for Surreal besides the default export.
  • More tests were added and generally improved.

Typing for .query() function

Where you previously had to type the .query() function like this:

surreal.query<Result<{
    id: string;
    field: string;
}>>("SELECT * FROM demo");

You will have to drop the Result type like this:

surreal.query<{
    id: string;
    field: string;
}>("SELECT * FROM demo");

Typing for .select(), .update(), .change() and .modify() functions

Please reference the description of #80, it greatly expands on the change.

What's Changed

New Contributors

Full Changelog: https://github.com/surrealdb/surrealdb.js/compare/v0.5.0...v0.6.0

Package Rankings
Top 3.09% on Npmjs.org
Top 4.61% on Deno.land
Related Projects
primate

Web framework focused on flexibility and developer freedom

16 Apr 2022 200
esm.sh

A fast, smart, & global CDN for modern(es2015+) web development.

06 Sep 2020 2,795
globalize

A JavaScript library for internationalization and localization that leverages the official Unicod...

28 Sep 2010 4,784
discordeno

Discord API library for Node and Deno

07 Feb 2020 784
deno-sqlite

Deno SQLite module

09 Dec 2019 403
node-bunyan

a simple and fast JSON logging module for node.js services

30 Jan 2012 7,173