npm package: @saiqa-tech/checkops
Description: A high-performance, production-ready Node.js package for creating dynamic forms with advanced optimizations, real-time monitoring, centralized question reusability, and enterprise-grade performance capabilities
Author: Saiqa Tech
Latest version: 3.1.0

# CheckOps

A production-ready Node.js npm package that enables developers to create dynamic forms with centralized question reusability and structured data submission capabilities.

[![npm version](https://badge.fury.io/js/%40saiqa-tech%2Fcheckops.svg)](https://www.npmjs.com/package/@saiqa-tech/checkops)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

## Features

- 🎯 **Dynamic Form Builder** - Create forms with flexible question types
- 🔄 **Question Reusability** - Centralized question bank for reusing questions across forms
- 🔑 **Stable Option Keys** - Option key-value system prevents data misalignment when labels change
- 📊 **Structured Data Submission** - Validated and sanitized submission handling
- 🔐 **Security First** - Built-in input sanitization and parameterized queries
- 🚀 **PostgreSQL 18 + JSONB** - High-performance database with flexible schema
- 📈 **Submission Analytics** - Built-in statistics and reporting
- 📝 **Option History Tracking** - Audit trail for all option label changes
- ⚡ **Performance Monitoring (v3.0.0)** - Real-time metrics and health checks
- 🚄 **Batch Operations (v3.0.0)** - High-performance bulk create operations (10-50x faster)
- 💾 **Intelligent Caching (v3.0.0)** - Automatic query caching with dependency tracking
- 🤖 **MCP Server (v3.0.0)** - Model Context Protocol integration for AI development tools
- 🧪 **80%+ Test Coverage** - Comprehensive unit and integration tests
- 📖 **Well Documented** - Complete API reference and usage guides

## Installation

```bash
npm install @saiqa-tech/checkops pg
```

**Note:** CheckOps requires PostgreSQL 12 or higher (PostgreSQL 18 recommended) and the `pg` package as peer dependencies.

## Quick Start

### 1. Initialize Database

First, run the database migrations:

```bash
# Set your database credentials
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=your_database
export DB_USER=postgres
export DB_PASSWORD=your_password

# Run migrations
npm run migrate
```

### 2. Initialize CheckOps

```javascript
import CheckOps from '@saiqa-tech/checkops';

const checkops = new CheckOps({
  host: 'localhost',
  port: 5432,
  database: 'your_database',
  user: 'postgres',
  password: 'your_password',
});

await checkops.initialize();
```

### 3. Create a Form

```javascript
const form = await checkops.createForm({
  title: 'Customer Feedback Form',
  description: 'Please share your experience with us',
  questions: [
    {
      questionText: 'What is your name?',
      questionType: 'text',
      required: true,
    },
    {
      questionText: 'What is your email?',
      questionType: 'email',
      required: true,
    },
    {
      questionText: 'How would you rate our service?',
      questionType: 'rating',
      options: [1, 2, 3, 4, 5],
      required: true,
    },
  ],
});

console.log('Form created:', form.id);
```

### 4. Submit Responses

```javascript
const submission = await checkops.createSubmission({
  formId: form.id,
  submissionData: {
    'What is your name?': 'John Doe',
    'What is your email?': 'john@example.com',
    'How would you rate our service?': 5,
  },
});

console.log('Submission created:', submission.id);
```

### 5. Get Analytics

```javascript
const stats = await checkops.getSubmissionStats(form.id);
console.log('Total submissions:', stats.totalSubmissions);
console.log('Question statistics:', stats.questionStats);
```

## Supported Question Types

- **text** - Single-line text input
- **textarea** - Multi-line text input
- **number** - Numeric input
- **email** - Email input with validation
- **phone** - Phone number input
- **date** - Date picker
- **time** - Time picker
- **datetime** - Date and time picker
- **select** - Single-choice dropdown
- **multiselect** - Multiple-choice dropdown
- **radio** - Radio button group
- **checkbox** - Checkbox group
- **boolean** - Yes/No toggle
- **file** - File upload
- **rating** - Star rating or numeric rating

## Documentation

### Getting Started
- [Quick Start](#quick-start) - Get up and running in minutes
- [Installation Guide](./CONTRIBUTING.md#setup-development-environment) - Detailed setup instructions

### Core Documentation
- [API Reference](./docs/API_REFERENCE.md) - Complete API documentation with v3.0.0 features
- [Usage Guide](./docs/USAGE_GUIDE.md) - Detailed usage examples and patterns
- [Examples](./docs/EXAMPLES.md) - Real-world code examples
- [Non-Technical Overview](./docs/NON_TECHNICAL_OVERVIEW.md) - Beginner-friendly explanation

### Architecture & Design
- [Database Schema](./docs/DATABASE_SCHEMA.md) - Database structure and relationships
- [Architecture](./docs/ARCHITECTURE.md) - System architecture and design patterns
- [Security](./docs/SECURITY.md) - Security best practices and guidelines

### v3.0.0 Features
- [Performance Monitoring](./docs/PERFORMANCE_MONITORING.md) - Metrics, monitoring, and health checks
- [Batch Operations](./docs/BATCH_OPERATIONS.md) - High-performance bulk operations
- [MCP Server](./MCP_SERVER_IMPLEMENTATION.md) - Model Context Protocol integration

### Migration & Support
- [Migration Guide](./docs/MIGRATION_GUIDE.md) - Upgrade between versions
- [FAQ](./docs/FAQ.md) - Frequently asked questions
- [Changelog](./CHANGELOG.md) - Version history and changes

## Database Requirements

- PostgreSQL 12 or higher (PostgreSQL 18 recommended)
- JSONB support (included in PostgreSQL 9.4+)
- Sufficient storage for form data

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Support

- GitHub Issues: [https://github.com/saiqa-tech/checkops/issues](https://github.com/saiqa-tech/checkops/issues)
- Documentation: [https://github.com/saiqa-tech/checkops](https://github.com/saiqa-tech/checkops)

## Recent Updates (v3.0.0)

### Performance Monitoring
Track operation performance, cache effectiveness, and system health in real-time:

```javascript
import CheckOps, { metricsCollector, getHealthCheckData } from '@saiqa-tech/checkops';

// Get performance metrics
const metrics = metricsCollector.getMetrics();
console.log('Cache hit rate:', metrics.cacheHits / (metrics.cacheHits + metrics.cacheMisses));

// Health check
const health = await getHealthCheckData();
console.log('System status:', health.status);

// Cache management
const cacheStats = checkops.getCacheStats();
await checkops.clearCache('stats');
```

### Batch Operations
Create multiple entities 10-50x faster with bulk operations:

```javascript
// Bulk create forms
const forms = await checkops.bulkCreateForms([
  { title: 'Form 1', questions: [...] },
  { title: 'Form 2', questions: [...] }
]);

// Bulk create submissions (perfect for imports)
const submissions = await checkops.bulkCreateSubmissions([
  { formId: 'FORM-001', submissionData: {...} },
  { formId: 'FORM-001', submissionData: {...} }
]);
```

### MCP Server Integration
Use CheckOps with AI development tools (Kiro, Cursor, Claude Code):

```bash
# Run MCP server
npx --package=@saiqa-tech/checkops@latest checkops-mcp-server
```

See [Performance Monitoring Guide](./docs/PERFORMANCE_MONITORING.md) and [Batch Operations Guide](./docs/BATCH_OPERATIONS.md) for details.

## Recent Updates (v2.1.0)

### Option Key-Value System
CheckOps now includes a stable option key-value system that ensures data integrity when option labels change:

```javascript
// Create question with simple options (auto-generates keys)
const question = await checkops.createQuestion({
  questionText: 'Select Priority',
  questionType: 'select',
  options: ['High', 'Medium', 'Low']
});

// Or use structured options with custom keys
const question2 = await checkops.createQuestion({
  questionText: 'Select Department',
  questionType: 'select',
  options: [
    { key: 'dept_eng', label: 'Engineering' },
    { key: 'dept_sales', label: 'Sales' }
  ]
});

// Update labels without breaking existing data
await checkops.updateOptionLabel(
  question2.id,
  'dept_eng',
  'Engineering & Technology',
  'admin@example.com'
);

// Track all label changes
const history = await checkops.getOptionHistory(question2.id, 'dept_eng');
```

See [CHANGELOG.md](CHANGELOG.md) for complete migration guide and breaking changes.

## Roadmap

- [ ] Export submissions to CSV/Excel
- [ ] Form templates library
- [ ] Conditional logic for questions
- [ ] Multi-language support for options
- [ ] Email notifications
- [ ] Webhook integrations
- [ ] React/Vue components

## Authors

**Saiqa Tech** - [https://github.com/saiqa-tech](https://github.com/saiqa-tech)

## Acknowledgments

Built with ❤️ for the developer community.