FileDB

⚡ A lightweight local JSON database for Deno.

Why Use FileDB?

• Simplicity: the module is semantic and easy to use.
• Flexibility: the module have multiple implementations for different situations.
• Suit with RESTful API: the module API is suited with RESTful API, you may refer to this example.

Quick Start

$ git clone https://github.com/jswildcards/filedb.git
$ cd ./filedb/example
$ deno run --allow-read --allow-write hello_world.ts

Getting Started

Setup

Let's start with importing the FileDB module and creating a database.

// main.ts
import { FileDB, Document } from "https://deno.land/x/filedb/mod.ts";
const db = new FileDB({ rootDir: "./data", isAutosave: true }); // create database with autosave

Then, create a User collection. The User collection has three attributes: firstName, lastName and favourites - a list of fruits the user loves!

To achieve this step, we need to define a User interface with attributes, and get (and implicitly create!) the User collection from the database.

// main.ts
interface User extends Document {
  firstName?: string;
  lastName?: string;
  favourites?: string[];
}
const users = await db.getCollection<User>("users"); // implicitly create and get User collection

Insert Records

We now have a User collection which can be inserted some records. Let's add one User first who is fancy foo and loves 🍎 Apple and 🍐 Pear.

// main.ts
await users.insertOne({
  firstName: "fancy",
  lastName: "foo",
  favourites: ["🍎 Apple", "🍐 Pear"],
});

Great! We have our first records inserted into the collection. Now let's try inserting more User by using insertMany method.

// main.ts
await users.insertMany([
  {
    firstName: "betty",
    lastName: "bar",
    favourites: ["🍌 Banana"],
  },
  {
    firstName: "benson",
    lastName: "baz",
    favourites: ["🍌 Banana"],
  },
]);

Retrieve Records

Now we have totally 3 User in our collection. We now want to know the information about fancy foo. We can use findOne method and pass a filtered object to do that.

// main.ts
console.log(users.findOne({ firstName: "fancy", lastName: "foo" }));

Great! But how about we now want to get all User who loves 🍌 Banana? We can use findMany method and pass a filter method to do that. Remember to call .value() after calling the findMany method.

// main.ts
console.log(users.findMany((el) => el.favourites?.includes("🍌 Banana")).value());

Update Records

As time goes by, some User may change their favourites. We now want to update only the first User who only loves 🍌 Banana before, loves 🍎 Apple and 🍐 Pear only in this moment.

In this case, the database will update the User betty bar as obviously she was inserted into the database earlier than User benson baz.

// main.ts
await users.updateOne(
  (el) => el.favourites?.[0] === "🍌 Banana",
  { favourites: ["🍎 Apple", "🍐 Pear"] },
);

Now we want to update all User whose lastName contains "ba". As besides love whatever they loved before, they all love "🍉 Watermelon" now.

// main.ts
await users.updateMany(
  (el) => el.lastName?.includes("ba"),
  (el) => {
    el.favourites = ["🍉 Watermelon", ...(el.favourites || [])];
    return el;
  },
);

Delete Records

Now we want to delete some records in our database. First we delete only one User whose firstName is fancy.

// main.ts
await users.deleteOne({ firstName: "fancy" });

Now we want to delete all User whose has at least one favourites.

// main.ts
await users.deleteMany((el) => (el.favourites?.length ?? []) >= 1);

Drop Database

// main.ts
await db.drop();

The whole example can be found here.

This module can do stuffs more than that! More examples can be found here.

Permission Required

This module requires --allow-read and --allow-write flags.

API

Please see the documentation.

Contribution

Welcome to Contribute to this module. Read this guideline to get started.

Disclaimer

This module is still unstable. So the module API may have breaking changes.

This module is only suitable for small-scaled projects. As when the database is large enough, it will be slow down with this file-based database structure and unoptimised searching algorithms.