diff --git a/README.md b/README.md index 256c3e4..be8d8fa 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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') @@ -108,8 +93,7 @@ type Data = { } const defaultData: Data = { messages: [] } -const adapter = new JSONFile('db.json') -const db = new Low(adapter, defaultData) +const db = await JSONFile('db.json') db.data.messages.push('foo') // ✅ Success db.data.messages.push(1) // ❌ TypeScript error @@ -117,9 +101,11 @@ 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 = { @@ -139,7 +125,7 @@ class LowWithLodash extends Low { const defaultData: Data = { posts: [], } -const adapter = new JSONFile('db.json') +const adapter = new JSONFile('db.json', defaultData) const db = new LowWithLodash(adapter) await db.read() @@ -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). diff --git a/src/browser.ts b/src/browser.ts index bfb05bc..3da4d0e 100644 --- a/src/browser.ts +++ b/src/browser.ts @@ -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' diff --git a/src/examples/browser.ts b/src/examples/browser.ts index 4511e22..6a4f869 100644 --- a/src/examples/browser.ts +++ b/src/examples/browser.ts @@ -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('db', defaultData) +const db = LocalStoragePreset('db', defaultData) db.data.messages.push('foo') diff --git a/src/examples/cli.ts b/src/examples/cli.ts index 1e9bda8..3c38963 100644 --- a/src/examples/cli.ts +++ b/src/examples/cli.ts @@ -1,4 +1,4 @@ -import { JSONSyncPreset } from '../presets/node/JSONPreset.js' +import { JSONSyncPreset } from '../presets/node.js' type Data = { messages: string[] @@ -6,7 +6,7 @@ type Data = { const message = process.argv[2] || '' const defaultData: Data = { messages: [] } -const db = JSONSyncPreset('file.json', defaultData) +const db = JSONSyncPreset('file.json', defaultData) db.data.messages.push(message) diff --git a/src/examples/in-memory.ts b/src/examples/in-memory.ts index 5978cf7..5a136cc 100644 --- a/src/examples/in-memory.ts +++ b/src/examples/in-memory.ts @@ -13,7 +13,7 @@ declare global { } type Data = Record -const defaultData = {} +const defaultData: Data = {} const adapter: SyncAdapter = process.env.NODE_ENV === 'test' ? new MemorySync() diff --git a/src/examples/server.ts b/src/examples/server.ts index 6ee9326..0dbb568 100644 --- a/src/examples/server.ts +++ b/src/examples/server.ts @@ -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()) diff --git a/src/node.ts b/src/node.ts index f702c0e..544f279 100644 --- a/src/node.ts +++ b/src/node.ts @@ -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' diff --git a/src/presets/browser.ts b/src/presets/browser.ts new file mode 100644 index 0000000..c123a81 --- /dev/null +++ b/src/presets/browser.ts @@ -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( + key: string, + defaultData: Data, +): LowSync { + const adapter = new LocalStorage(key) + const db = new LowSync(adapter, defaultData) + db.read() + return db +} + +export function SessionStoragePreset( + key: string, + defaultData: Data, +): LowSync { + const adapter = new SessionStorage(key) + const db = new LowSync(adapter, defaultData) + db.read() + return db +} diff --git a/src/presets/browser/WebStoragePreset.ts b/src/presets/browser/WebStoragePreset.ts deleted file mode 100644 index d110ad3..0000000 --- a/src/presets/browser/WebStoragePreset.ts +++ /dev/null @@ -1,13 +0,0 @@ -import { WebStorage } from '../../adapters/browser/WebStorage.js' -import { LowSync } from '../../index.js' - -export function WebStoragePreset( - key: string, - defaultData: Data, - storage: Storage = localStorage, -): LowSync { - const adapter = new WebStorage(key, storage) - const db = new LowSync(adapter, defaultData) - db.read() - return db -} diff --git a/src/presets/node/JSONPreset.ts b/src/presets/node.ts similarity index 79% rename from src/presets/node/JSONPreset.ts rename to src/presets/node.ts index bb3cebd..3d4df0a 100644 --- a/src/presets/node/JSONPreset.ts +++ b/src/presets/node.ts @@ -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( filename: string | URL,