TypeScript icon, indicating that this package has built-in type declarations

0.1.15 • Public • Published


[ Webwite | Manual | 手册 ]

This is a Node.js implementation of FiDB -- a suite of protocols to use file system as database.

Including a command-line tool to initialize and maintain database.

  help [name]             Display help for a command
  init:database [path]    Initialize a directory to be a database
  serve:database [path]   Serve a database
  serve:subdomain [path]  Serve many databases using subdomain-based routing

And a HTTP server to generate REST API from a database.

POST   {data-path}?kind=data
GET    {data-path}?kind=data
PUT    {data-path}?kind=data
PATCH  {data-path}?kind=data
DELETE {data-path}?kind=data

GET    {data-directory}?kind=data-find

POST   {file}?kind=file
GET    {file}?kind=file
PUT    {flie}?kind=file
DELETE {flie}?kind=file

GET    {flie}?kind=file-metadata

POST   {flie}?kind=file-rename

POST   {directory}?kind=directory
GET    {directory}?kind=directory
DELETE {directory}?kind=directory


The ethos of the FiDB project is the following "what if ...?"s.

What if we use file system as database?

What if we generate HTTP API from the database,
instead of writing trivial CRUD code over and over again?

What if we write web apps in a way that a user can switch backend,
even using their local backend?



Node.js version must be >= 20.8.0.

  • For the recursive option to readdir and opendir.

Command line tool

Install it by the following command:

npm install -g fidb

The command line program is called fidb.


Init a database

A database is just a directory of subdirectories and JSON data files, with a database.json config file, and with some more data files serve as detailed system configurations.

Use the fidb init:database command to create a database:

fidb init:database hello-world

Example console output of fidb init:database:

17:07:19.297 [init] -- {"directory":"/databases/hello-world"}
17:07:19.301 [initDatabaseConfigFile] -- {"file":"/databases/hello-world/database.json"}

Let's see what files are created:


Serve one database

Use the fidb serve:database command to serve a database:

fidb serve:database hello-world

The default port of the server is 5108, which looks like FiDB isn't it?

Serve many databases

Use the fidb serve:subdomain command to serve many databases in one directory, using subdomain-based routing.

For example, I have a VPS machine, where I put all my databases in the /databases directory.


I bought a domain for my server -- say, and configured my DNS to resolve and * to my server.

I also created certificate files for my domain using certbot.

I can use fidb serve:subdomain command to serve all of the databases in /databases directory.

fidb serve:subdomain /databases/database.json

Where /databases/database.json is:

  "server": {
    "hostname": "",
    "port": 5108,
    "tls": {
      "cert": "/etc/letsencrypt/live/",
      "key": "/etc/letsencrypt/live/"
  • When using fidb serve:subdomain, the server.hostname option is required.

  • And each database in /databases might have it's own database.json config file.

Then I can access all my databases via subdomain of

If no subdomain is given in a request, www/ will be used as the default subdomain directory (while no redirect will be done).

Thus the following websites have the same contents:

Register a user

Use POST {data-file}?kind=password-register HTTP request to register a new user:

curl -X POST "" --data-binary @-<< END

  "password": "wonderland",
  "data": {
    "name": "Alice"


Example response:

  "name": "Alice",
  "@path": "users/alice",
  "@revision": "b0b913da866105ad66299baf6aa4d783",
  "@createdAt": 1696152632809,
  "@updatedAt": 1696152632809

New data files for the user will be created:


Login a user

Use POST {data-file}?kind=password-login HTTP request to login an initialized user:

curl -X POST "" --data-binary @-<< END

  "password": "wonderland"


Example response:

{ "token":"07cb46bde600f9ab97a22ecee8bc2389" }

New data file for the token will be created:


Which can be used in the Authorization header for future requests.

Authorization: token 34dbf6a79e7968ffc3cda1b51c3fada9

Config logger

We can config logger in /databases/database.json:

  "logger": {
    "name": "pretty-line",
    "disableRequestLogging": true

The type of logger options are:

export type LoggerOptions = {
  name: "json" | "silent" | "pretty" | "pretty-line"
  disableRequestLogging?: boolean

The default logger options are:

  "name": "pretty-line",
  "disableRequestLogging": false

Get free certificate

You can use certbot to get free certificate for your domains.

After install certbot, I prefer creating certificate via DNS TXT record, using the following command:

sudo certbot certonly --manual --preferred-challenges dns

Then you can follow the prompt of certbot to create the certificate files, during which you will need to add TXT record to the DNS record of your domain to accomplish the challenge given by certbot.

Use systemd to start service

Install service:

sudo cp <name>.service /etc/systemd/system/

Using service:

sudo systemctl start <name>.service
sudo systemctl enable <name>.service
sudo systemctl status <name>.service

To view log:

journalctl -f -u <name>.service

Reload systemd config files:

sudo systemctl daemon-reload


npm install           # Install dependencies
npm run build         # Compile `src/` to `lib/`
npm run build:watch   # Watch the compilation
npm run format        # Format the code
npm run test          # Run test
npm run test:watch    # Watch the testing


To make a contribution, fork this project and create a pull request.

Please read the before you change the code.

Remember to add yourself to AUTHORS. Your line belongs to you, you can write a little introduction to yourself but not too long.






Package Sidebar


npm i fidb

Weekly Downloads






Unpacked Size

625 kB

Total Files


Last publish


  • xieyuheng