A driver to query Fauna databases in browsers, Node.js, and other Javascript runtimes
WARNING This driver is in beta release and not recommended for production use. It operates with the Fauna database service via an API which is also in beta release, and is not recommended for production use. This driver is not compatible with v4 or earlier versions of Fauna. If you would like to participate in the private beta program please contact product@fauna.com.
See the Fauna Documentation for additional information how to configure and query your databases.
This driver can only be used with FQL X, and is not compatible with earlier versions of FQL. To query your databases with earlier API versions, see the faunadb package.
import { Client, fql } from "fauna";
// configure your client
const client = new Client({
secret: YOUR_FAUNA_SECRET,
});
try {
// create a Collection
const collection_query = fql`Collection.create({ name: "Dogs" })`;
const collection_result = await client.query(collection_query);
// define some data
const dog = { name: "Scout" };
// create a Document
const document_query = fql`
Dogs.create(${dog}) {
id,
ts,
name
}
`;
const document_result = await client.query(document_query);
} catch (error) {
if (error instanceof fauna.FaunaError) {
// handle errors
}
}
This Driver supports and is tested on:
The fauna-js driver is available on npm. You can install with your package manager of choice:
npm install fauna
or
yarn add fauna
The driver is additionally made available to browsers via CDN:
<script type="module">
import * as fauna from "https://cdn.jsdelivr.net/npm/fauna@latest/dist/browser/index.js";
</script>
<html>
<head></head>
<body>
<h1>Test</h1>
</body>
<script type="module">
import * as fauna from "https://cdn.jsdelivr.net/npm/fauna@latest/dist/browser/index.js";
/* ... */
</script>
</html>
import * as fauna from "fauna";
or using require for CommonJS files
const fauna = require("fauna");
With TypeScript, you can apply a type parameter to your result.
import { Document, type DocumentT } from "fauna";
type User = {
name: string;
email: string;
};
const query = fql`User.create({
name: "Alice",
email: "alice@site.example",
})`;
const result = await client.query<DocumentT<User>>(query);
const user_doc = result.data;
// you have typesafe access to `Document` and `User` fields
console.assert(user_doc instanceof Document);
console.assert(user_doc.id);
console.assert(user_doc.ts);
console.assert(user_doc.name === "Alice");
console.assert(user_doc.email === "alice@site.example");
Options are available to configure queries on each request.
import { Client, type QueryRequestHeaders } from "fauna";
const client = new Client();
const options: QueryRequestHeaders = {
format: "tagged",
linearized: false,
query_timeout_ms: 60_000,
max_contention_retries: 5,
query_tags: { name: "readme query" },
traceparent: "00-750efa5fb6a131eb2cf4db39f28366cb-000000000000000b-00",
typecheck: true,
};
const result = await client.query(SOME_QUERY, options);
The client can be configured for your specific environment. You can also provide query options that will be sent by default with every request
import { Client, endpoints, type ClientConfiguration } from "fauna";
const config: ClientConfiguration = {
// configure client
secret: YOUR_FAUNA_SECRET,
endpoint: endpoints.default,
max_conns: 10,
// set default query options
format: "tagged",
linearized: false,
query_timeout_ms: 60_000,
max_contention_retries: 5,
query_tags: { name: "readme query" },
traceparent: "00-750efa5fb6a131eb2cf4db39f28366cb-000000000000000b-00",
typecheck: true,
};
const client = new Client(config);
The driver will default to configuring your client with the values of the FAUNA_SECRET and FAUNA_ENDPOINT environment variable.
For example, if you set the following environment variables:
export FAUNA_SECRET=YOUR_FAUNA_SECRET
export FAUNA_ENDPOINT=https://db.fauna.com/
you can create a client without additional options
const client = new Client()
Query statistics are returned with successful query responses and ServiceErrors.
import {
ServiceError,
type QueryInfo,
type QueryStats,
type QuerySuccess,
} from "fauna";
try {
const result: QuerySuccess<string> = await client.query(fql`"Hello world"`);
const stats: QueryStats | undefined = result.stats;
} catch (error: any) {
if (error instanceof ServiceError) {
const info: QueryInfo = error.queryInfo;
const stats: QueryStats | undefined = info.stats;
}
}
console.log(stats);
/* example output
* ```
* {
* compute_ops: 1,
* read_ops: 0,
* write_ops: 0,
* query_time_ms: 15,
* storage_bytes_read: 0,
* storage_bytes_write: 0,
* contention_retries: 0
* }
* ```
*/
This driver uses a template-based approach to composing queries and operations. The advantage of this design is that you can prototype and test your queries in the Fauna dashboard shell, and then cut-and-paste those queries as templates in your client, which are executed in Fauna via this driver. You can parameterize your query by adding placeholders to the template, and then pass a set of arguments to the query() method, or resolve the placeholders with string interpolation.
You can write a query in pure FQL X using the driver's fql tag template function. Each FQL X language driver exposes the raw FQL X language - there is no need to learn a new framework for each language.
Here's an example in pure FQL X:
const result = await client.query(fql`
let create_user = (params) => if (params.email != null) {
User.create(params)
} else {
null
}
let u = create_user({
name: "Alice",
email: "alice@site.example",
})
u {
id,
ts,
name,
email
}
`);
Template literals in Javascript make it easy to pass in variables to your query and create reusable pieces of FQL.
// a reusable anonymous function to create Users with validated parameters
const create_user = fql`
(params) => if (params.email != null) {
User.create(params)
} else {
null
}
`;
// a reusable projection to format User documents
const user_projection = fql`{ id, ts, name, email }`;
// an object to pass to the query
const user_params = {
name: "Alice",
email: "alice@site.example",
};
// put everything together
const composed_query = fql`
let create_user = ${create_user}
let u = create_user(${user_params})
u ${user_projection}
`;
const result2 = await client.query(composed_query);
Any contributions are from the community are greatly appreciated!
If you have a suggestion that would make this better, please fork the repo and create a pull request. You may also simply open an issue. We provide templates, so please complete those to the best of your ability.
Don't forget to give the project a star! Thanks again!
gh repo clone fauna/fauna-js if you use the GitHub CLIyarn installyarn test. This will start local fauna containers, verify they're up and run all tests.Linting runs automatically on each commit.
If you wish to run on-demand run yarn lint.
Distributed under the MPL 2.0 License. See LICENSE for more information.
FAQs
A driver to query Fauna databases in browsers, Node.js, and other Javascript runtimes
The npm package fauna receives a total of 1,832 weekly downloads. As such, fauna popularity was classified as popular.
We found that fauna demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.