Skip to content

Commit

Permalink
feat: add presets to simplify use
Browse files Browse the repository at this point in the history
  • Loading branch information
typicode committed Oct 14, 2023
1 parent 42b382e commit da2169f
Show file tree
Hide file tree
Showing 10 changed files with 55 additions and 46 deletions.
43 changes: 21 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ If you like lowdb, please [sponsor](https://github.com/sponsors/typicode).
- Safe atomic writes
- Hackable:
- Change storage, file format (JSON, YAML, ...) or add encryption via [adapters](#adapters)
- Add lodash, ramda, ... for super powers!
- Extend it with lodash, ramda, ... for super powers!

## Install

Expand All @@ -59,25 +59,10 @@ npm install lowdb
_Lowdb is a pure ESM package. If you're having trouble using it in your project, please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)._

```js
// Remember to set type: module in package.json or use .mjs extension
import { join, dirname } from 'node:path'
import { fileURLToPath } from 'node:url'
import { JSONPreset } from 'lowdb/node'

import { Low } from 'lowdb'
import { JSONFile } from 'lowdb/node'

// db.json file path
const __dirname = dirname(fileURLToPath(import.meta.url))
const file = join(__dirname, 'db.json')

// Configure lowdb to write data to JSON file
const adapter = new JSONFile(file)
const defaultData = { posts: [] }
const db = new Low(adapter, defaultData)

// Read data from JSON file, this will set db.data content
// If JSON file doesn't exist, defaultData is used instead
await db.read()
const db = await JSONPreset('db.json', defaultData)

// Create and query items using plain JavaScript
db.data.posts.push('hello world')
Expand Down Expand Up @@ -108,18 +93,19 @@ type Data = {
}

const defaultData: Data = { messages: [] }
const adapter = new JSONFile<Data>('db.json')
const db = new Low<Data>(adapter, defaultData)
const db = await JSONFile<Data>('db.json')

db.data.messages.push('foo') // ✅ Success
db.data.messages.push(1) // ❌ TypeScript error
```

### Lodash

You can also add lodash or other utility libraries to improve lowdb.
You can extend lowdb with Lodash (or other libraries).

```ts
import { Low } from 'lowdb'
import { JSONFile } from 'lowdb/node'
import lodash from 'lodash'

type Post = {
Expand All @@ -139,7 +125,7 @@ class LowWithLodash<T> extends Low<T> {
const defaultData: Data = {
posts: [],
}
const adapter = new JSONFile<Data>('db.json')
const adapter = new JSONFile<Data>('db.json', defaultData)
const db = new LowWithLodash(adapter)
await db.read()

Expand All @@ -153,6 +139,19 @@ See [`src/examples/`](src/examples) directory.

## API

### Presets

Lowdb provides four presets for common cases.

- `JSONPreset(filename, defaultData)`
- `JSONSyncPreset(filename, defaultData)`
- `LocalStoragePreset(name, defaultData)`
- `SessionStoragePreset(name, defaultData)`

See [`src/examples/`](src/examples) directory for usage.

Lowdb is extremely flexible, if you need to extend it or modify its behavior, use the classes and adapters below instead of the presets.

### Classes

Lowdb has two classes (for asynchronous and synchronous adapters).
Expand Down
2 changes: 1 addition & 1 deletion src/browser.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
export * from './adapters/browser/LocalStorage.js'
export * from './adapters/browser/SessionStorage.js'
export * from './presets/browser/WebStoragePreset.js'
export * from './presets/browser.js'
4 changes: 2 additions & 2 deletions src/examples/browser.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
import { WebStoragePreset } from '../presets/browser/WebStoragePreset.js'
import { LocalStoragePreset } from '../presets/browser.js'

type Data = {
messages: string[]
}

const defaultData: Data = { messages: [] }
const db = WebStoragePreset<Data>('db', defaultData)
const db = LocalStoragePreset<Data>('db', defaultData)

db.data.messages.push('foo')

Expand Down
4 changes: 2 additions & 2 deletions src/examples/cli.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
import { JSONSyncPreset } from '../presets/node/JSONPreset.js'
import { JSONSyncPreset } from '../presets/node.js'

type Data = {
messages: string[]
}

const message = process.argv[2] || ''
const defaultData: Data = { messages: [] }
const db = JSONSyncPreset('file.json', defaultData)
const db = JSONSyncPreset<Data>('file.json', defaultData)

db.data.messages.push(message)

Expand Down
2 changes: 1 addition & 1 deletion src/examples/in-memory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ declare global {
}

type Data = Record<string, unknown>
const defaultData = {}
const defaultData: Data = {}
const adapter: SyncAdapter<Data> =
process.env.NODE_ENV === 'test'
? new MemorySync<Data>()
Expand Down
2 changes: 1 addition & 1 deletion src/examples/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
import express from 'express'
import asyncHandler from 'express-async-handler'

import { JSONPreset } from '../presets/node/JSONPreset.js'
import { JSONPreset } from '../presets/node.js'

const app = express()
app.use(express.json())
Expand Down
2 changes: 1 addition & 1 deletion src/node.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
export * from './adapters/node/JSONFile.js'
export * from './adapters/node/TextFile.js'
export * from './presets/node/JSONPreset.js'
export * from './presets/node.js'
23 changes: 23 additions & 0 deletions src/presets/browser.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import { LocalStorage } from '../adapters/browser/LocalStorage.js'
import { SessionStorage } from '../adapters/browser/SessionStorage.js'
import { LowSync } from '../index.js'

export function LocalStoragePreset<Data>(
key: string,
defaultData: Data,
): LowSync<Data> {
const adapter = new LocalStorage<Data>(key)
const db = new LowSync<Data>(adapter, defaultData)
db.read()
return db
}

export function SessionStoragePreset<Data>(
key: string,
defaultData: Data,
): LowSync<Data> {
const adapter = new SessionStorage<Data>(key)
const db = new LowSync<Data>(adapter, defaultData)
db.read()
return db
}
13 changes: 0 additions & 13 deletions src/presets/browser/WebStoragePreset.ts

This file was deleted.

6 changes: 3 additions & 3 deletions src/presets/node/JSONPreset.ts → src/presets/node.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { Memory, MemorySync } from '../../adapters/Memory.js'
import { JSONFile, JSONFileSync } from '../../adapters/node/JSONFile.js'
import { Low, LowSync } from '../../core/Low.js'
import { Memory, MemorySync } from '../adapters/Memory.js'
import { JSONFile, JSONFileSync } from '../adapters/node/JSONFile.js'
import { Low, LowSync } from '../core/Low.js'

export async function JSONPreset<Data>(
filename: string | URL,
Expand Down

0 comments on commit da2169f

Please sign in to comment.