@yaro.page/nano-db

📖 Nano-DB Usage Guide

This guide covers how to set up, manage, and use the nano-db package, a lightweight database abstraction for the nanoweb ecosystem.

📌 Project Structure

The nano-db package follows a modular structure:

nano-db/
├── lib/            # Source code
│   ├── Manifest.js
│   ├── ManifestChange.js
│   ├── ManifestNode.js
│   ├── ManifestNodes.js
│   ├── NANODb.js
│   ├── NANODbOptions.js
│   ├── SearchEntries.js
│   ├── SearchEntry.js
│   ├── SearchIndex.js
│   ├── index.js
├── test/           # Test files
|   ├── 00-README.md.test.js  # Document generator and tester
│   ├── Manifest.test.js
│   ├── NANODb.test.js
├── package.json    # Package metadata and scripts
├── vitest.config.js # Vitest configuration
└── README.md      # This documentation

🔗 Requirements

1. Node.js runtime environment You must have Node v22+ installed.
2. pnpm package manager You must have the pnpm package manager installed.
3. nano-format The nano-format package is a peer dependency and must be installed.

🔧 Setting Up the Package

1. Install the package:

   pnpm add nano-db

2. Install peer dependencies:

   pnpm add nano-format

3. Build the package:

   pnpm build

🚗 Running the Development Environment

• Start the development server:

  pnpm dev

• Run tests:

  pnpm test

• Build the package:

  pnpm build

• Lint the code:

  pnpm lint

🔄 Managing Dependencies & Versions

Updating Dependencies

Before committing, ensure all workspace dependencies are resolved:

pnpm ws:latest

To use workspace versions during development:

pnpm ws:workspace

Checking for Issues Before Commit

pnpm ws:check

🏗 Releasing the Package

1. Ensure all changes are committed and pushed.
2. Run the release script:

   pnpm release

   This will:
   • Run tests and linting
   • Build the package
   • Tag the new version in Git
   • Publish to npm
   • Push commits and tags

🛸 Contributing

1. Create a new branch:

   git checkout -b feature/my-update

2. Make changes and commit:

   git commit -m "Add new feature"

3. Push your branch and open a pull request.

⚙️ Useful Utility Scripts

Command	Description
pnpm build	Build the package (generates documentation)
pnpm test	Run tests
pnpm lint	Lint the code
pnpm dev	Start development server
pnpm release	Release the package
pnpm ws:check	Validate package.json & pre-commit hooks
pnpm ws:latest	Replace workspace:* with actual versions
pnpm ws:workspace	Convert all versions to workspace:*

🛠️ Troubleshooting

• Dependency Issues: Run pnpm install and pnpm ws:latest.
• Build Errors: Ensure nano-format is installed and run pnpm build.
• Test Failures: Check test files and run pnpm test.
• Pre-commit Hook Failures: Verify .husky/pre-commit and run pnpm ws:check.

---

With these steps, you can efficiently use and maintain nano-db! 🚀