📖 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! 🚀