local-cache-json

Library for managing local cache with json data.

Requires Node.js >= 18 (uses the native fetch API for download()).

Usage example

const { DbBase } = require('local-cache-json')
const path = require('path')

const resDir = path.join(__dirname, 'resources')
const db = new DbBase({ path: path.join(resDir, 'data.json') })

// existing data at config.path is already loaded at this point (see constructor)
const data = db.data || {}
data['newParam'] = 'paramValue'
db.save(true, true)

new DbBase(config, manifest, logger)

• config:
  • path: local file used to persist/load the cache
  • url: URL of a shared/global cache to pull via download()
  • backPath: (optional) folder used for timestamped backups on save()
• manifest: (optional) a companion object (e.g. another DbBase instance) exposing { data, save(overwrite) }, used to track per-key metadata (content length, hash, last-changed date) so repeated save()/download() calls can detect unchanged content
• logger: (optional) object with log/warn/error methods; defaults to console

The constructor loads any existing data from config.path automatically — you don't need to call load() yourself unless you want to reload after an external change.

Properties

• db.data — the underlying data object
• db.empty — true if data has no keys

Methods

• db.load() — (re)loads data from config.path; no-op if the file doesn't exist
• db.save(overwrite, sort, recursive) — persists data to config.path
  • overwrite (boolean): if falsy and the file already exists, save() does nothing
  • sort (boolean | string): if truthy, keys are sorted before saving — true for default order, or a locale string (e.g. 'zh') for locale-aware sorting
  • recursive (boolean): also sort keys of nested objects (only applies when sort is truthy)
  • if config.backPath is set and the file already exists, the previous version is renamed into backPath with a timestamp suffix before being overwritten
• db.clear() — resets data to {}
• db.download(skipIfSame) — fetches JSON from config.url and replaces data with it. Returns a Promise resolving with the downloaded JSON string (or undefined if skipIfSame is true and the manifest shows the content is unchanged), rejecting on network/HTTP failure. A call made while a previous one is still pending is ignored.
• db.getTable(table) — returns data[table]
• db.findTableRaw(table, col, val, ignorecase) — returns the first row in data[table] where row[col] === val (or a case-insensitive string match if ignorecase is true)
• db.getTableRawIndex(table, col, val) — same lookup as above, returning the row's index instead

getTable/findTableRaw/getTableRawIndex assume data is shaped as { tableName: [ { col: val, ... }, ... ] }.

Static helpers

• DbBase.JSONparse(json) — JSON.parse that logs and returns undefined instead of throwing
• DbBase.JSONsave(obj, filePath) / DbBase.JSONsaveAsync(obj, filePath) — write obj as formatted JSON to filePath (sync/async), returning the JSON string
• DbBase.JSONload(filePath) — reads and parses a JSON file, returning undefined if it's missing, empty, or invalid
• DbBase.sortByKey(obj, locale, recursive) — returns a copy of obj with keys sorted (optionally locale-aware, optionally recursive)

Thanks

If you like our ideas and want to support further development, you can donate here: