@nan0web/db-fs

Database provider for nan•web with node:fs. Allows saving, loading, writing, and scanning files with async support, ideal for lightweight monorepo tooling.

Installation

How to install with npm?

npm install @nan0web/db-fs

How to install with pnpm?

pnpm add @nan0web/db-fs

How to install with yarn?

yarn add @nan0web/db-fs

Quick Start

How to save and load a JSON file?

import DBFS from "@nan0web/db-fs"
const db = new DBFS({ root: '__test_quick_start__' })
await db.connect()
const data = { name: 'Test', value: 42 }
await db.saveDocument('test.json', data)
const loaded = await db.loadDocument('test.json')
console.info(loaded) // ← { name: "Test", value: 42 }

How to append content to a TXT file?

import DBFS from "@nan0web/db-fs"
const db = new DBFS({ root: '__test_append__' })
await db.connect()
await db.writeDocument('log.txt', 'First line\n')
await db.writeDocument('log.txt', 'Second line')
const content = await db.loadDocument('log.txt')
console.info(content) // ← "First line\nSecond line"

Directory Scanning

findStream(uri, { limit = -1, sort = "name", order = "asc", skipStat = false, skipSymbolicLink = true })

Asynchronously scans directories with configurable limits and sorting.

• Parameters
  • uri (string) – Path to scan
  • options.limit (number) – Max entries to return (-1 for all)
  • options.sort (string) – Sort by "name", "mtime", or "size"
  • options.order (string) – Sort order "asc" or "desc"
  • options.skipStat (boolean) – Skip file stats for faster scan
  • options.skipSymbolicLink (boolean) – Ignore symbolic links

How to scan directory with findStream?

import FS from "@nan0web/db-fs"
const db = new FS()
await db.connect()
const files = []
for await (const entry of db.findStream('src', { limit: 99, sort: 'name', order: 'asc' })) {
	files.push(entry.file.path)
}
console.info(files) // ← ['file-system', 'DBFS.js', 'DBFS.test.js']

File Formats

Supports automatic handling of:

• .json – Pretty-printed
• .jsonl – Array of JSON lines
• .csv, .tsv – Delimited tables
• .txt – Plain text

How to save and load CSV file?

import DBFS from "@nan0web/db-fs"
const db = new DBFS({ root: '__test_csv__' })
await db.connect()
const data = [
	{ Name: 'John', Age: 30 },
	{ Name: 'Jane', Age: 25 },
]
await db.saveDocument('people.csv', data)
const loaded = await db.loadDocument('people.csv')
console.info(loaded) // ← [ { Name: "John", Age: 30 }, { Name: "Jane", Age: 25 } ]

Playground

Try examples safely with CLI sandbox:

How to run CLI sandbox?

git clone https://github.com/nan0web/db-fs.git
cd db-fs
npm install
npm run play

API Reference

saveDocument(uri, data)

Saves data to a file with auto-formatting.

• Parameters

  • uri (string) – File path
  • data (any) – Data to save, formatted by extension

• Returns

  • Promise – Success status

How to test saveDocument API?

import DBFS from "@nan0web/db-fs"
const db = new DBFS({ root: '__test_save_api__' })
await db.connect()
const result = await db.saveDocument('test.json', { a: 1 })
console.info(result) // ← true

loadDocument(uri, defaultValue?)

Loads file content parsed by extension.

• Parameters

  • uri (string) – File path
  • defaultValue (any) – Fallback if not found

• Returns

  • Promise – Parsed content or default

How to test loadDocument API?

import DBFS from "@nan0web/db-fs"
const db = new DBFS({ root: '__test_load_api__' })
await db.connect()
const empty = await db.loadDocument('missing.json', {})
console.info(empty) // ← {}
await db.saveDocument('data.json', { b: 2 })
const loaded = await db.loadDocument('data.json')
console.info(loaded) // ← { b: 2 }

writeDocument(uri, chunk)

Appends raw string chunk to file.

• Parameters

  • uri (string) – File path
  • chunk (string) – Text to append

• Returns

  • Promise – Success status

How to test writeDocument API?

import DBFS from "@nan0web/db-fs"
const db = new DBFS({ root: '__test_write_api__' })
await db.connect()
await db.writeDocument('log.txt', 'start\n')
await db.writeDocument('log.txt', 'done')
const result = await db.loadDocument('log.txt')
console.info(result) // ← "start\ndone"

dropDocument(uri)

Deletes a file or directory.

• Parameters

  • uri (string) – Path to delete

• Returns

  • Promise – Success status

• Throws

  • Error if access violation or non-empty directory

How to test dropDocument API?

import DBFS from "@nan0web/db-fs"
const db = new DBFS({ root: '__test_drop_api__' })
await db.connect()
await db.saveDocument('temp.txt', 'Delete me')
const existsBefore = await db.loadDocument('temp.txt')
console.info(existsBefore) // ← "Delete me"
await db.dropDocument('temp.txt')
const missingAfter = await db.loadDocument('temp.txt', null)
console.info(missingAfter) // ← null

Java•Script

Fully typed with TypeScript declaration files and JSdoc:

How many d.ts files cover it?

Contributing

How to contribute? - check CONTRIBUTING.md

License

How to license? – see LICENSE