feat: add presets to simplify use

Author: typicode

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,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 = {
@@ -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()
 
@@ -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).

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'

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<Data>('db', defaultData)
+const db = LocalStoragePreset<Data>('db', defaultData)
 
 db.data.messages.push('foo')
 

src/examples/cli.ts

@@ -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)
 

src/examples/in-memory.ts

@@ -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>()

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())

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'

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<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
+}

src/presets/browser/WebStoragePreset.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<Data>(
   filename: string | URL,