New Fauna JS driver available for alpha testing

[n400]

Help us improve Fauna's upcoming JS driver

We're working on a new JavaScript driver that supports ECMAScript modules (ESM) to support tree shaking, allow for smaller bundle sizes, and generally provide a more modern development experience.

Please note that this driver version is not officially supported and should NOT be used in production, because we might continue to add breaking changes and there may be bugs as we continue to improve the experience.

That said, we would be very thankful if you would be kind enough to test it in a development environment and provide us feedback and/or questions.

Installation instructions

To try the new driver, you’ll need to change the FaunaDB dependency :
npm install https://github.com/fauna/faunadb-js.git#esm_build --save

In package.json, you should now see this line:
"faunadb": "git+https://github.com/fauna/faunadb-js.git#esm_build",
instead of:
"faunadb": "file:../../faunadb-js",

Migration guide from 4.X.X to 5.X.X

To take advantage of ESM, you will need to make some minor changes to your app code:

Faunadb imports

const faunadb = require('faunadb')
- const { Ref, FaunaDate, Bytes, ... } = faunadb.values
+ const { Ref, FaunaDate, Bytes, ... } = faunadb

- const { InvalidArity, FaunaHTTPError, BadRequest, ... } = faunadb.errors
+ const { InvalidArity, FaunaHTTPError, BadRequest, ... } = faunadb

- const { logger, showRequestResult } = faunadb.clientLogger
+ const { logger, showRequestResult } = faunadb

Import query functions

All query functions have been removed from the main package and hosted under sub-module faunadb/query.

CommonJS

const faunadb = require('faunadb');
-const q = faunadb.query;
+const q = require('faunadb/query');

ECMAScript

import { Client } from 'faunadb'

// Import all queries by one command
import * as q from 'faunadb/query'

// Named imports
import { Select, Var } from 'faunadb/query'

// Deep imports
import Select from 'faunadb/query/Select'
import Var from 'faunadb/query/Var'

Although most modern bundle tools are able to tree-shake the package with named imports, we recommend using deep imports.

Renamed queries

Due to the restriction of JS reserved words, some queries have been renamed.

client.query(
-  Get(Function('increment'))
+  Get(FaunaFunction('increment'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

client.query(
-  Paginate(Match(Index('name'))),
+  Paginate(Match(FaunaIndex('name'))),
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

Streaming API

The streaming API is no longer included by default.

const faunadb = require('faunadb')
const q = require('faunadb/query')
+ const Stream = require('faunadb/stream')
const client = new faunadb.Client({secret: 'YOUR_FAUNA_SECRET'})
+ const streamApi = new StreamApi({ client })
const docRef = q.Ref(q.Collection('Scores'), '1')

let stream
const startStream = () => {
-  stream = client.stream.document(docRef)
+  stream = streamApi.document(docRef)
  .on('snapshot', snapshot => {
    report(snapshot)
  })
  .on('version', version => {
    report(version)
  })
  .on('error', error => {
    console.log('Error:', error)
    stream.close()
    setTimeout(startStream, 1000)
  })
  .start()
}

startStream()

Providing feedback and asking questions

To provide feedback or ask questions, please feel free to reply to this Discussion topic and/or email product at fauna dot com

[PierBover]

It's looking great @n400 !

Is this new version going to improve the client-side size issues discussed here?

Personally, I'm fine with the breaking changes. Would be great if the dashboard's shell supported these FQL name changes. I find myself frequently copying/pasting JS code into the shell and viceversa.

[n400]

Thank you!

Is this new version going to improve the client-side size issues discussed here?

Yes, it should. The current driver already has some changes to significantly decrease the bundle size since the discussion you linked, so the change in size is not very dramatic, but it does help a bit more. Give it a spin and let me know what you think--there is more we can do if it's still too large.

Would be great if the dashboard's shell supported these FQL name changes. I find myself frequently copying/pasting JS code into the shell and viceversa.

Good catch; I'll make sure that's included. What do you think of the name changes themselves? Would you have used different names?

[PierBover]

What do you think of the name changes themselves? Would you have used different names?

Personally I like adding Fauna in front of the FQL functions as it makes it super obvious.

Another option could be to follow the same pattern as the Fauna Python driver. Eg: Instead of Map it uses map_.

https://docs.fauna.com/fauna/current/api/fql/functions/map?lang=python

Although it's easy to miss the little underscore at the end. Happened to me when using the Python driver...

[Vadorequest]

The new API looks cleaner and more like what I'd expect.

The new naming (Fauna prefix) is a breaking change, but as long as it is interoperable with the Fauna Web Shell, it doesn't matter too much. (I also copy/paste and try to keep my code exactly the same as the web shell to avoid c/p issues)

[BetaConnector]

@n400, i tried the new version with vite, and I am getting the following error:

[fireridlle]

@BetaConnector this is vite issue. reference vitejs/vite#2802

[jsejcksn]

Hello. These instructions seem specific to Node.js. How can I use it in a browser (or in Deno)? (I am looking for instructions for using import, not a UMD module).

[ptpaterson]

Closing this, as we will be maintaining v4 of this driver while also moving forward with our v10 driver in a different repository: https://github.com/fauna/fauna-js

Thanks all, for your feedback!