PandaDB Node.js SDK - Development Guide

This guide explains how to build and publish the PandaDB Node.js SDK.

Development Setup

1. Clone the repository:

git clone <your-repo-url>
cd sdk

2. Install dependencies:

npm install

Building the SDK

1. Run the build command:

npm run build

This will:

• Clean the dist directory
• Compile TypeScript to JavaScript
• Generate type declaration files
• Create source maps

The build output will be in the dist directory:

• dist/*.js - Compiled JavaScript files
• dist/*.d.ts - TypeScript declaration files
• dist/*.map - Source maps

Testing

1. Run tests:

npm test

2. Run linting:

npm run lint

3. Format code:

npm run format

Publishing to npm

1. Login to npm:

npm login

2. Update version (choose one):

npm version patch  # For bug fixes (0.0.x)
npm version minor  # For new features (0.x.0)
npm version major  # For breaking changes (x.0.0)

3. Build and publish:

npm run build
npm publish

The package will be published as @pandadb/node.

Development Workflow

1. Make changes to files in src/
2. Run tests: npm test
3. Run linting: npm run lint
4. Build: npm run build
5. Test the built package:

   # In another project
   npm install ../path/to/sdk

Package Structure

sdk/
├── src/
│   ├── client.ts      # Main SDK implementation
│   ├── types.ts       # TypeScript type definitions
│   ├── errors.ts      # Error handling classes
│   └── index.ts       # Public API exports
├── package.json       # Package configuration
└── tsconfig.json      # TypeScript configuration

Local Testing

To test the SDK locally in another project:

1. In the SDK directory:

npm run build
npm pack

2. In your test project:

npm install ../path/to/pandadb-node-0.1.0.tgz

Continuous Integration

Before publishing:

1. Ensure all tests pass
2. Check linting
3. Verify the build works
4. Test the package locally

Publishing Checklist

• [ ] Update version in package.json
• [ ] Run tests
• [ ] Run linting
• [ ] Build the package
• [ ] Test the built package locally
• [ ] Update README if needed
• [ ] Commit all changes
• [ ] Create git tag
• [ ] Push to repository
• [ ] Publish to npm

Example Usage

After publishing, users can install the package:

npm install @pandadb/node

And use it in their code:

import { PandaDB } from '@pandadb/node';

const client = new PandaDB({
  token: 'YOUR_AUTH_TOKEN'
});

// Execute a query
const result = await client.query(
  'db_123abc',
  'SELECT * FROM users WHERE age > ?',
  [18]
);

// Use real-time subscriptions
const unsubscribe = client.subscribe(
  'db_123abc',
  'users',
  {
    onCreate: (user) => console.log('New user:', user),
    onUpdate: (user) => console.log('Updated user:', user),
    onDelete: (id) => console.log('Deleted user:', id)
  }
);

// Clean up when done
unsubscribe();

Troubleshooting

Common issues:

1. Build errors:

   • Run npm install to ensure all dependencies are installed
   • Check TypeScript errors in your IDE
   • Run npm run lint to find issues

2. Publishing errors:

   • Ensure you're logged in to npm: npm login
   • Check if the package name is available
   • Verify you have publish access to the @pandadb organization

3. Type errors:

   • Check that all types are properly exported in index.ts
   • Verify tsconfig.json settings
   • Ensure declaration files are generated

Support

For any issues:

1. Check the troubleshooting guide
2. Run tests and linting
3. Contact the PandaDB team