https://github.com/gmencz/faunadb

TypeScript-first FaunaDB client with static type inference.
https://github.com/gmencz/faunadb

Last synced: about 2 months ago
JSON representation

TypeScript-first FaunaDB client with static type inference.

• Host: GitHub
• URL: https://github.com/gmencz/faunadb
• Owner: gmencz
• License: mit
• Created: 2021-09-21T19:33:29.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2022-04-01T12:28:00.000Z (over 2 years ago)
• Last Synced: 2024-10-14T11:43:15.419Z (2 months ago)
• Language: TypeScript
• Homepage:
• Size: 1.51 MB
• Stars: 18
• Watchers: 1
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        


  

    

  

  

  

    

  

  

    

  

  

    

  

  

    

  



## Table of Contents

- [Table of Contents](#table-of-contents)

- [Introduction](#introduction)

- [Installation](#installation)

- [Usage](#usage)

  - [Client configuration](#client-configuration)

    - [secret](#secret)

    - [url](#url)

    - [fetch](#fetch)

  - [Schema](#schema)

- [Issues](#issues)

  - [🐛 Bugs](#-bugs)

  - [💡 Feature Requests](#-feature-requests)

- [LICENSE](#license)

## Introduction

TypeScript-first FaunaDB client with static type inference. You declare what your FaunaDB schema looks like and the client will ensure your queries are written correctly.

One of the main focuses of the library is to keep the bundle size as small as possible due to FaunaDB being used the most in serverless environments where script size is limited.

## Installation

```

npm install @gmencz/faunadb

```

## Usage

```ts

import { Client, QueryBuilder, SchemaTypes } from '@gmencz/faunadb';

// Create a new FaunaDB client with your credentials.

// Get them from your dashboard (https://dashboard.fauna.com/).

const client = new Client({

  secret: 'your-faunadb-key-secret',

});

// Define your FaunaDB schema. Your schema type should follow the base type of `SchemaTypes`, you can hover over `SchemaTypes` or go to definition to see what it looks like. This will help the `QueryBuilder` validate your queries.

type Schema = SchemaTypes & {

  Collections: {

    countries: {

      name: string;

    };

  };

  Indexes: ['all_countries'];

};

// Create a new `QueryBuilder` and provide your schema as a generic. A `QueryBuilder` helps you build queries using FQL (https://docs.fauna.com/fauna/current/api/fql/), all non-deprecated FQL built-in functions are available and the API of every function is identical to the API described in the docs so you should look at the official FaunaDB docs for learning about a function. That's all! Now you can run your queries in a type-safe way:

const q = new QueryBuilder();

type CountriesQuery = Schema['Collections']['countries'][];

// The `query()` method accepts a generic which allows you to tell the client what you're expecting back to be returned from the query.

const countries = await faunadb.query(

  q.Let(

    {

      paginationResult: q.Map(

        q.Paginate(q.Match(q.Index('all_countries'))),

        q.Lambda('page', q.Select(['data'], q.Get(q.Var('page'))))

      ),

    },

    q.Select(['data'], q.Var('paginationResult'))

  )

);

console.log(countries);

```

### Client configuration

#### secret

Opaque bearer token, associated with a token document or key document

within Fauna, that provides access to a specific database.

A secret is displayed only once at creation time; it should be stored

securely, and needs to be revoked and recreated if lost.

#### url

The URL where your database is located. It's common to use `http://localhost:8443`

in development for accesing a local FaunaDB database. For production, you can use

one of the region groups's URL. Learn more about region groups here: https://docs.fauna.com/fauna/current/api/fql/region_groups.

Defaults to the classic region group URL `https://db.fauna.com`. A `RegionGroupURL` enum is exported with the URLs for each region group.

For example, if you chose the EU region group, you could set it up like this:

```ts

import { Client, RegionGroupURL } from '@gmencz/faunadb';

const client = new Client({

  // other config...

  url: RegionGroupURL.EU,

});

```

#### fetch

A custom `fetch` implementation, this is useful where your runtime implements a custom version of `fetch` like when using Cloudflare Workers.

Cloudflare Workers example:

```ts

import { Client, RegionGroupURL } from '@gmencz/faunadb';

const client = new Client({

  // other config...

  fetch: (input, init) => {

    const signal = init?.signal;

    delete init?.signal;

    const abortPromise = new Promise((_, reject) => {

      if (signal) {

        signal.onabort = reject;

      }

    });

    return Promise.race([abortPromise, fetch(input, init)]);

  },

});

```

### Schema

These are the parts of your schema you can define:

```ts

AccessProviders?: string[] | undefined;

Collections?: Record | undefined;

Databases?: string[] | undefined;

Functions?: Record | undefined;

Indexes?: string[] | undefined;

Roles?: string[] | undefined;

```

## Issues

### 🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

[**See Bugs**](https://github.com/gmencz/faunadb/issues?utf8=%e2%9c%93&q=is%3aissue+is%3aopen+sort%3acreated-desc+label%3abug)

### 💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding

a 👍. This helps maintainers prioritize what to work on.

[**See Feature Requests**](https://github.com/gmencz/faunadb/issues?utf8=%e2%9c%93&q=is%3aissue+is%3aopen+sort%3areactions-%2b1-desc+label%3aenhancement)

## LICENSE

MIT