Skip to content

lwhiteley/feathers-lowdb

Repository files navigation

feathers-lowdb

NPM version Downloads Test Runner

feathers-lowdb is a FeathersJS database adapter for Lowdb, a small JSON and YAML database for Node, and the browser. LowDB can store data in-memory or on the filesystem which makes it useful as a persistent storage without a separate database server.

$ npm i feathers-lowdb

Try it Online

Advanced

LowDB benefits over NeDB, SQLite and others

  • No External Dependencies 🫧: LowDB is a self-contained JavaScript library, whereas NeDB and SQLite require external dependencies. This makes LowDB more convenient to use, as you don't need to manage additional installations or dependencies.

  • Flexibility🤸‍♀️: LowDB operates directly on JSON files, allowing you to easily manipulate and access the data using standard JavaScript objects and arrays. This flexibility can be advantageous for certain use cases, such as simple data storage or prototyping.

  • Portability ✈️: Since LowDB is based on JSON files, it can be easily shared and moved between different platforms or systems. This makes it suitable for scenarios where data needs to be transferred or accessed across multiple environments.

  • Great DX 🧑‍💻: The output is aesthetically pleasing by default, making it easier for humans to read without additional tools.

  • Popular 💅: It is widely used, ensuring good maintenance and a large community.

  • Modular ☸️: It utilizes ES Modules, making it as lightweight as possible by default, which is great for frontends.

  • Predictable 🔮: Document updates are actually saved instead of being copied as new versions at the bottom of the file, making debugging of userland code easier.

  • Testable 🐑: It is suitable for testing, as the output is more predictable and less cryptic. You can load snapshots, make changes, and expect the output file to be perfectly matched.

  • Lean design 🐦: Indexes can be saved outside of the database or as a separate collection, rather than being appended as a strange line in your collection.

API

yaml([options])

Returns a new database instance initialized with the given options.

import { LowDBService } from 'feathers-lowdb'

export const createModel = (app: Application) => {
  return new LowDBService({
    filename: 'users.yaml', // or users.json
    id: '_id', // todo: https://github.com/feathersjs/feathers/issues/2839
    startId: 1,
    paginate: {
      default: 2,
      max: 4
    }
  })
}

Options:

  • filename (_optional, default /tmp/low-123-321.yaml) - The full path to the file
  • id (optional, default: 'id') - The name of the id field property.
  • startId (optional, default: 0) - An id number to start with that will be incremented for every new record (unless it is already set).
  • store (optional) - An object with id to item assignments to pre-initialize the data store
  • events (optional) - A list of custom service events sent by this service
  • paginate (optional) - A pagination object containing a default and max page size
  • whitelist (DEPRECATED) - renamed to allow
  • allow (optional) - A list of additional query parameters to allow
  • multi (optional) - Allow create with arrays and update and remove with id null to change multiple items. Can be true for all methods or an array of allowed methods (e.g. [ 'remove', 'create' ])

Example

Here is an example of a Feathers server with a messages LowDB service that supports pagination and persists to messages.yaml:

$ npm i @feathersjs/feathers @feathersjs/koa @feathersjs/socketio feathers-lowdb@alpha

In app.js:

import { feathers } from '@feathersjs/feathers'
import {
  koa,
  rest,
  bodyParser,
  errorHandler,
  serveStatic,
} from '@feathersjs/koa'
import socketio from '@feathersjs/socketio'
import { LowDBService } from 'feathers-lowdb'

// Creates an ExpressJS compatible Feathers application
const app = koa(feathers())

// Use the current folder for static file hosting
app.use(serveStatic('.'))
// Register the error handle
app.use(errorHandler())
// Parse JSON request bodies
app.use(bodyParser())

// Register REST service handler
app.configure(rest())
// Configure Socket.io real-time APIs
app.configure(socketio())
// Register our messages service
app.use(
  '/messages',
  new LowDBService({
    filename: 'messages.yaml', // or messages.json
    id: '_id', // todo: https://github.com/feathersjs/feathers/issues/2839
    startId: 1,
    paginate: {
      default: 2,
      max: 4
    }
  })
);

// Create a dummy Message
app
  .service('messages')
  .create({
    text: 'Message created on server',
  })
  .then((message) => console.log('Created message', message))


app.listen(3030, () => {
  console.log(`Feathers server listening`)
})

Run the example with node app and go to localhost:3030/messages.

Try this example online: https://stackblitz.com/fork/lowdb-qs-first-app

License

Copyright (c) 2023

Licensed under the MIT license.