{"id":13489260,"url":"https://github.com/SilverFox70/faunadb-connector","last_synced_at":"2025-03-28T04:31:00.718Z","repository":{"id":41785794,"uuid":"238296842","full_name":"SilverFox70/faunadb-connector","owner":"SilverFox70","description":"A basic wrapper class for the FaunaDB Javascript API","archived":false,"fork":false,"pushed_at":"2023-05-07T22:43:48.000Z","size":406,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-03T06:34:09.094Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SilverFox70.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-02-04T20:13:52.000Z","updated_at":"2021-05-06T20:00:25.000Z","dependencies_parsed_at":"2024-01-16T09:25:52.046Z","dependency_job_id":null,"html_url":"https://github.com/SilverFox70/faunadb-connector","commit_stats":{"total_commits":12,"total_committers":2,"mean_commits":6.0,"dds":0.08333333333333337,"last_synced_commit":"b743ce9fc10d853ef24382c887c309a069245d3b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SilverFox70%2Ffaunadb-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SilverFox70%2Ffaunadb-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SilverFox70%2Ffaunadb-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SilverFox70%2Ffaunadb-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SilverFox70","download_url":"https://codeload.github.com/SilverFox70/faunadb-connector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245970403,"owners_count":20702406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T19:00:21.374Z","updated_at":"2025-03-28T04:31:00.377Z","avatar_url":"https://github.com/SilverFox70.png","language":"JavaScript","funding_links":[],"categories":["Tools","JavaScript"],"sub_categories":["Wrappers and libraries"],"readme":"# FaunaDB Connector\n\nThis is a convenience wrapper class for the basic functionality of the FaunaDB Javascript API. This wrapper helps to simplify some of the syntax for these basic operations while still exposing the faunaDB package and Fauna Client. You can find more information on the FaunaDB javascript API [here](https://docs.fauna.com/fauna/current/drivers/javascript.html) and basic tutorials [here](https://docs.fauna.com/fauna/current/tutorials/crud). \n\n## Basic use\n\nTo use the wrapper, import it and instantiate with your secret key. Using an admin key will allow you full access to actions within your fauna account while using other keys with different permissions or roles may limit what queries may be run.\n\n``` javascript\nconst FaunaConnection = require('./faunadb-connector')\nconst fauna = new FaunaConnection({secret: \u003cyour_fauna_secret_here\u003e})\n```\n\nAll of the class functions return a promise. The connection can then be used like this:\n``` javascript\nfauna\n  .createCollection('blog_posts')\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nThe underlying functions and client can be accessed as below for writing your own queries for those cases where the provided basic functions lack the scope you need.\n``` javascript\nfauna.q is faunadb.query\nfauna.client is the faunadb.Client\n``` \n  \n[Visit this webpage to view the class api](https://silverfox70.github.io/faunadb-connector/FaunaConnection.html).\n\n## Usage\n\n### Create a database\n\nThis will work only as long as the permissions/role of the secret key you provided are scoped to allow database creation.\n``` javascript\nfauna\n  .createDB('blog_posts')\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nThe output should look like:\n``` bash\n{ \n  ref: Database(\"blog_posts\"), \n  ts: 1580933987495000, \n  name: 'blog_posts' \n}\n```\n\n### Create Collection\n``` javascript\nfauna\n  .createCollection('authors')\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```  \n\nThe output should look like:\n``` bash\n{ \n  ref: Collection(\"authors\"),\n  ts: 1580934704606000,\n  history_days: 30,\n  name: 'authors' \n}\n```\n\n### Create Index\n\n`createIndex(name, src, terms=null, values=null)`\n\n| params    | type   | description                                |\n|---------|--------|--------------------------------------------|\n| name    | string | a descriptive name for this index          |\n| src     | string | the source collection this index will be applied to |\n| terms   | object | the terms to use for the index             |\n| values  | object | the values to be used for the index        |\n\nIf you have just created a collection you will need to create an _all_ index so that you can easily retrieve the items in your collection. Below is the most basic index you can create and requires no other arguments other than a descriptive index name and the collection that is the source.\n\n``` javascript\nfauna\n  .createIndex('all_authors', 'authors')\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n``` \n\nThe output should look like:\n``` bash\n{ \n  ref: Index(\"all_authors\"),\n  ts: 1580935056400000,\n  active: true,\n  serialized: true,\n  name: 'all_authors',\n  source: Collection(\"authors\"),\n  partitions: 8 \n}\n```\n\nIndexes can be substantially more complicated than what you see above and much of that discussion is beyond the scope of this document. For more information on using Indexes, please [check this out](https://docs.fauna.com/fauna/current/tutorials/indexes/). \n\nAs to how to create more detailed indexes with this wrapper, know that you can pass in a **terms** and **values** object for building your index. For example, let's suppose you have a _collection_ of authors, and each author document has a first name and a last name field. We might want to sort our authors by last name and then by first name in ascending order, so let's create an index to do that.\n\n``` javascript\n\nconst values = [\n  { field: [\"data\", \"last\"] },\n  { field: [\"data\", \"first\"] },\n  { field: [\"ref\"] }\n]\n\nfauna\n  .createIndex('authors_sort_by_last_first_asc', 'authors', null, values)\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nOur response should look something like:\n```bash\n{ \n  ref: Index(\"authors_sort_by_last_first_asc\"),\n  ts: 1580935873770000,\n  active: true,\n  serialized: true,\n  name: 'authors_sort_by_last_first_asc',\n  source: Collection(\"authors\"),\n  values:\n    [ \n      { field: [Array] }, \n      { field: [Array] }, \n      { field: [Array] } \n    ],\n  partitions: 8 \n}\n```\n\n### Create a document\n\nAll documents live inside _collections_, so to create a new document in FaunaDB, we pass in the collection name and the document we wish to store.\n\n``` javascript\nconst author = {\n  first_name: \"Alex\",\n  last_name: \"Smith\"\n}\n\nfauna\n  .create('authors', author)\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nThe response should look something like:\n```bash\n{ \n  ref: Ref(Collection(\"authors\"), \"256563456795214345\"),\n  ts: 1580936829280000,\n  data: { first_name: 'Alex', last_name: 'Smith' } \n}\n```\n\n### Creating multiple documents at once\n\nThe same `#create` function will also accept an array of documents. Each element in the array will be created as its own record.\n\n``` javascript\nconst authorList = [\n  {\n    first_name: \"Jack\",\n    last_name: \"London\"\n  },\n  {\n    first_name: \"Aldous\",\n    last_name: \"Huxley\"\n  },\n  {\n    first_name: \"Jane\",\n    last_name: \"Austen\"\n  },\n  {\n    first_name: \"Maya\",\n    last_name: \"Angelou\"\n  },\n]\n\nfauna\n  .create('authors', authorList)\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nThe response should look something like:\n```bash\n[ \n  { \n    ref: Ref(Collection(\"authors\"), \"256569179938754057\"),\n    ts: 1580942287315000,\n    data: { first_name: 'Jack', last_name: 'London' } \n  },\n  { \n    ref: Ref(Collection(\"authors\"), \"256569179938752009\"),\n    ts: 1580942287315000,\n    data: { first_name: 'Aldous', last_name: 'Huxley' } \n  },\n  { \n    ref: Ref(Collection(\"authors\"), \"256569179938750985\"),\n    ts: 1580942287315000,\n    data: { first_name: 'Jane', last_name: 'Austen' } \n  },\n  { \n    ref: Ref(Collection(\"authors\"), \"256569179938753033\"),\n    ts: 1580942287315000,\n    data: { first_name: 'Maya', last_name: 'Angelou' } \n  } \n]\n```\n\n### Creating with custom ID\n\nThe process is the same as above for creating documents, except that an array of touples must be passed in the function below. Each touple consists of `[\u003ccustom_id\u003e, \u003cdocument\u003e]`. Each custom_id must be unique.\n\n**fauna.createWithCustomID(collection, touples)**\n\n### Getting a document\n\nThere are several methods for retrieving a document from a collection within a database. The most basic `#get` works with the `ref`, or ID of the document and the collection name.\n\n\n``` javascript\nfauna\n  .get('authors', '256569179938753033')\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n``` \n\nThe response should look something like:\n```bash\n{ \n  ref: Ref(Collection(\"authors\"), \"256569179938753033\"),\n  ts: 1580942287315000,\n  data: { first_name: 'Maya', last_name: 'Angelou' } \n}\n```\n\nIn order to get a document based on data within a document itself, we must first have created and index for this and told Fauna which term we would like to search on. For example, let's consider that we created an index as below:\n\n``` javascript\n\nconst terms = [{ field: ['data', 'title'] }]\n\nfauna.createIndex('posts_by_title', 'posts', term, null)\n```\n\nThe above index would allow us to get a particular 'post' document by searching for it's title as shown below:\n\n``` javascript\nfauna\n  .getMatch('posts_by_title', 'My cat and other marvels')\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nWhich, if the document exists, will return something like:\n``` bash\n{ \n  ref: Ref(Collection(\"posts\"), \"256027278950009353\"),\n  ts: 1580425490300000,\n  data: { title: 'My cat and other marvels' } \n}\n```\n\n### Getting Multiple Documents\n\nThere are many options which can be used and I encourage you to check out [the class api](https://silverfox70.github.io/faunadb-connector/FaunaConnection.html) for greater detail since there a many options which are supported. Here we will go over the most basic implementation of retrieving all of the docs within a collection.\n\n``` javascript\nfauna\n  .getAllDocsByIndex('all_authors')\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nThis call should return all of the documents in the collection in a form like this, where the nested `data` Object is the document itself:\n``` bash\n{ \n  data:[ \n    { \n      ref: Ref(Collection(\"authors\"), \"256563456795214345\"),\n       ts: 1580936829280000,\n       data: [Object] \n    },\n    { \n      ref: Ref(Collection(\"authors\"), \"256568566847898122\"),\n       ts: 1580941702620000,\n       data: [Object] \n    },\n    { \n      ref: Ref(Collection(\"authors\"), \"256569179938750985\"),\n       ts: 1580942287315000,\n       data: [Object] \n    },\n    { \n      ref: Ref(Collection(\"authors\"), \"256569179938752009\"),\n       ts: 1580942287315000,\n       data: [Object] \n    },\n    { \n      ref: Ref(Collection(\"authors\"), \"256569179938753033\"),\n       ts: 1580942287315000,\n       data: [Object] \n    },\n    { \n      ref: Ref(Collection(\"authors\"), \"256569179938754057\"),\n       ts: 1580942287315000,\n       data: [Object] \n    },\n    { \n      ref: Ref(Collection(\"authors\"), \"256569241022497289\"),\n       ts: 1580942345550000,\n       data: [Object] \n    } \n  ] \n}\n```\n\n### Updating a document\n\nTo modify an existing document simply pass in the new data along with the reference to the document and collection.\n``` javascript\nconst birthdate = {\n  dob: \"01/12/1876\"\n}\n\nfauna\n  .update('authors', \"256569179938754057\", birthdate)\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nThe response should look something like this:\n``` bash\n{ \n  ref: Ref(Collection(\"authors\"), \"256569179938754057\"),\n  ts: 1581012583020000,\n  data: { \n      first_name: 'Jack', \n      last_name: 'London', \n      dob: '01/12/1876' \n  } \n}\n```\n\n\u003e Note: we also support the `replace` function using the same parameter list as update. See the [Fauna docs](https://docs.fauna.com/fauna/current/tutorials/crud#replace) for more information on the difference between **update** and **replace**.\n\n### Deleting a document\n\nA document can be removed using the `delete` function, passing in the collection and document reference.\n\n``` javascript\nfauna\n  .delete('authors', \"256569179938752009\")\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nThe response returns the document that has been deleted.\n``` bash\n{ \n  ref: Ref(Collection(\"authors\"), \"256569179938752009\"),\n  ts: 1580942287315000,\n  data: { \n    first_name: 'Aldous', last_name: 'Huxley' \n  } \n}\n```\n\n## Using the underlying API\n\nThere may be actions you desire to take for which there is not yet a wrapper function in this class. Consider the example from the Fauna Tutorials for [Create a user defined function](https://docs.fauna.com/fauna/current/tutorials/crud_examples#udf-create) - we can use our `fauna` instance to write this like so:\n\n``` javascript\nfauna\n  .client\n  .query(\n    fauna.q.CreateFunction({\n      name: \"create_entry\",\n      body: fauna.q.Query(\n        fauna.q.Lambda(\n          ['title', 'body'],\n          fauna.q.Create(\n            fauna.q.Collection('posts'),\n            {\n              data: {\n                title: fauna.q.Var('title'),\n                body: fauna.q.Var('body')\n              }\n            }\n          )\n        )\n      ),\n      permissions: { call: 'public' },\n      role: 'server'\n    })\n  )\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.log(err))\n```\n\nWhich will return a response like this:\n``` bash\n{ \n  ref: Function(\"create_entry\"),\n  ts: 1581013836710000,\n  name: 'create_entry',\n  body: Query(\n    Lambda(\n      [\"title\", \"body\"], \n      Create(\n        Collection(\"posts\"), \n        {\n          data: {\n            title: Var(\"title\"), \n            body: Var(\"body\")\n          }\n        }\n      )\n    )\n  ),\n  permissions: { call: 'public' },\n  role: 'server' \n}\n```\n\n## Future Goals\n\nThis is only the beginning of a basic wrapper to make implementing calls to the FaunaDB Javascript API easier to re-use. While the hope is to expand upon this, there is no desire to deal with every possible scenario a developer might encounter. That being said, if anyone has a particular feature they would like to see, or has encountered a bug or other unanticipated behavior, please [submit an issue](https://github.com/SilverFox70/faunadb-connector/labels) and I will look into it as I am able.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSilverFox70%2Ffaunadb-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSilverFox70%2Ffaunadb-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSilverFox70%2Ffaunadb-connector/lists"}