# lowdb 文档(译)


lowdb Github

Build Status npm

用于Node,Electron和浏览器的小型JSON数据库。由Lodash提供支持。 ⚡️

db.get('posts')
  .push({ id: 1, title: 'lowdb is awesome'})
  .write()

# 用法

npm install lowdb
const low = require('lowdb')
const FileSync = require('lowdb/adapters/FileSync')

const adapter = new FileSync('db.json')
const db = low(adapter)

// 设置一些默认值 (如果您的JSON文件为空,则为必需)
db.defaults({ posts: [], user: {}, count: 0 })
  .write()

// 新增一个post
db.get('posts')
  .push({ id: 1, title: 'lowdb is awesome'})
  .write()

// 使用Lodash简写语法设置用户
db.set('user.name', 'typicode')
  .write()
  
// 增量计数
db.update('count', n => n + 1)
  .write()

数据保存到 db.json

{
  "posts": [
    { "id": 1, "title": "lowdb is awesome"}
  ],
  "user": {
    "name": "typicode"
  },
  "count": 1
}

您可以使用任何强大的 lodash functions, 就像 _.get_.find 这样的简写语法。

// 为了提高性能,如果仅从数据库中读取数据,请使用.value()而不是.write()
db.get('posts')
  .find({ id: 1 })
  .value()

一般而言,Lowdb非常适合命令行界面,小型服务器,Electron应用程序和npm软件包。

它支持Node浏览器并使用lodash API, 所以它非常易于学习实际上,如果您了解Lodash,您已经知道如何使用lowdb了 😉

重要 lowdb不支持集群,并且可能与非常大的JSON文件有关(约200MB)

# 安装

npm install lowdb

或者,如果您使用 yarn

yarn add lowdb

还可以在unpkg上使用UMD版本进行测试和快速原型制作:

<script src="https://unpkg.com/lodash@4/lodash.min.js"></script>
<script src="https://unpkg.com/lowdb@0.17/dist/low.min.js"></script>
<script src="https://unpkg.com/lowdb@0.17/dist/LocalStorage.min.js"></script>
<script>
  var adapter = new LocalStorage('db')
  var db = low(adapter)
</script>

# API

low(adapter)

返回具有以下描述的其他属性和功能的lodash chain

db.[...].write()db.[...].value()

write() 将数据库写入状态。

另一方面, value() 只是_.prototype.value() 并应用于执行不会更改数据库状态的链。

db.set('user.name', 'typicode')
  .write()

请注意, db.[...].write() 是语法糖,等效于

db.set('user.name', 'typicode')
  .value()

db.write()

db._

数据库lodash实例。 用它来添加自己的实用程序功能或第三方混合程序,例如 underscore-contrib 或者 lodash-id.

db._.mixin({
  second: function(array) {
    return array[1]
  }
})

db.get('posts')
  .second()
  .value()

db.getState()

返回数据库状态。

db.getState() // { posts: [ ... ] }

db.setState(newState)

替换数据库状态。

const newState = {}
db.setState(newState)

db.write()

使用adapter.write持久化数据库(取决于适配器,可能会返回一个Promise)。

// 使用 lowdb/adapters/FileSync
db.write()
console.log('State has been saved')

// 使用 lowdb/adapters/FileAsync
db.write()
  .then(() => console.log('State has been saved'))

db.read()

使用storage.read选项读取源代码(取决于适配器,可能会返回一个Promise)。

// 使用 lowdb/FileSync
db.read()
console.log('State has been updated')

// 使用 lowdb/FileAsync
db.read()
  .then(() => console.log('State has been updated'))

# 适配器 API

请注意,这仅适用于与Lowdb捆绑在一起的适配器。第三方适配器可能有不同的选择。

为了方便起见,FileSyncFileAsyncLocalBrowser接受以下选项:

  • defaultValue 如果文件不存在,则此值将用于设置初始状态(默认值:{}
  • serialize/deserialize 写入之前和读取之后使用的函数 (默认值: JSON.stringifyJSON.parse)
const adapter = new FileSync('array.yaml', {
  defaultValue: [],
  serialize: (array) => toYamlString(array),
  deserialize: (string) => fromYamlString(string)
})

# 指南

# 如何查询

使用lowdb,您可以使用所有 lodash API,因此,有许多方法可以查询和处理数据。以下是一些入门示例。

请注意,数据是通过引用返回的,这意味着对返回对象的修改可能会更改数据库。为了避免这种行为,您需要使用 .cloneDeep().

同样,方法的执行是懒惰的,也就是说,执行被推迟到 .value() 或者 .write() 调用后。

# 从现有的JSON文件读取

如果您正在从文件适配器读取,则该路径是相对于执行路径(CWD)的,而不是相对于您的代码的。

my_project/
  src/
    my_example.js
  db.json 

因此,您可以这样读取:

// 文件 src/my_example.js
const adapter = new FileSync('db.json')

// 使用 lowdb/FileAsync
db.read()
  .then(() => console.log('Content of my_project/db.json is loaded'))

# Examples

检查 posts 是否存在

db.has('posts')
  .value()

设置 posts

db.set('posts', [])
  .write()

对前五个post进行排序

db.get('posts')
  .filter({published: true})
  .sortBy('views')
  .take(5)
  .value()

获取 post 标题

db.get('posts')
  .map('title')
  .value()

获取 posts 的数量

db.get('posts')
  .size()
  .value()

使用路径获取第一个post的标题。

db.get('posts[0].title')
  .value()

更新一个 post

db.get('posts')
  .find({ title: 'low!' })
  .assign({ title: 'hi!'})
  .write()

移除 posts.

db.get('posts')
  .remove({ title: 'low!' })
  .write()

移除一个属性

db.unset('user.name')
  .write()

对 posts 深度克隆

db.get('posts')
  .cloneDeep()
  .value()

# 如何使用基于ID的资源

能够使用id获取数据可能非常有用,尤其是在服务器中。要将基于id的资源支持添加到lowdb,您有2个选择。

shortid 更加简化,并返回创建资源时可以使用的唯一ID。

const shortid = require('shortid')

const postId = db
  .get('posts')
  .push({ id: shortid.generate(), title: 'low!' })
  .write()
  .id

const post = db
  .get('posts')
  .find({ id: postId })
  .value()

lodash-id 提供了一组用于创建和处理基于ID的资源帮助。

const lodashId = require('lodash-id')
const FileSync = require('lowdb/adapters/FileSync')

const adapter = new FileSync('db.json')
const db = low(adapter)

db._.mixin(lodashId)

// 我们需要设置一些默认值, 如果该集合还不存在
// 我们也可以存储我们的集合
const collection = db
  .defaults({ posts: [] })
  .get('posts')

// 插入一个新的 post...
const newPost = collection
  .insert({ title: 'low!' })
  .write()

// ...并使用其ID检索它
const post = collection
  .getById(newPost.id)
  .value()

# 如何创建自定义适配器

low() 允许自定义适配器,因此您实际上可以使用任何格式将数据保存到任何存储中。

class MyStorage {
  constructor() {
    // ...
  }

  read() {
    // 应该返回数据(对象或数组)或Promise
  }

  write(data) {
    // 应该返回一个Promise或者不返回任何东西
  }
}

const adapter = new MyStorage(args)
const db = low(adapter)

有关示例,请参见 src/adapters

# 如何加密数据

FileSync, FileAsyncLocalStorage 允许自定义 serializedeserialize 函数。您可以使用它们添加加密逻辑。

const adapter = new FileSync('db.json', {
  serialize: (data) => encrypt(JSON.stringify(data)),
  deserialize: (data) => JSON.parse(decrypt(data))
})

# 更改日志

release notes 中查看每个版本的更改

# 局限

Lowdb是一种无需设置数据库服务器即可方便地存储数据的方法。它足够快且安全,可以用作嵌入式数据库。

但是,如果您寻求高性能和可扩展性而不是简单性,那么您可能应该坚持使用MongoDB等传统数据库。

# 许可证

MIT - Typicode 🌵

0 0
0

评论区

0 / 300
提交评论
暂无评论