qclair-shared-models

A comprehensive npm package for managing MongoDB models across multiple repositories with automatic synchronization, version control, and type safety.

🚀 Features

• 🔄 Model Synchronization: Automatically sync models across repositories
• 📦 Version Control: Track model versions and detect changes
• 🎯 Smart Updates: Only update models that have changed
• 🛡️ Safe Operations: Backup existing models before updates
• 🔍 Change Detection: Compare model versions and content hashes
• 📋 Model Management: List and manage all available models
• 🔧 CLI Tool: Easy-to-use command line interface
• 📝 TypeScript Support: Full TypeScript definitions included
• 🎨 ES Modules: Modern ES module support

📦 Installation

Publishing the Package

# Build and publish (for maintainers)
npm run build
npm publish --access public

Using in Your Projects

# Install the package
npm install qclair-shared-models

# For development/CLI usage
npm install -g qclair-shared-models

🎯 Usage

Importing Models (ESM & CommonJS)

ESM (TypeScript/ESM Node.js)

import { User, SubscriptionPlan, Enterprise } from "qclair-shared-models";
// ...
import type {
  UserDocument,
  SubscriptionPlanDocument,
} from "qclair-shared-models";

CommonJS (require syntax)

const { User, SubscriptionPlan, Enterprise } = require("qclair-shared-models");
// ...

Functional API (Recommended)

import { syncModels, checkUpdates, ModelManager } from "qclair-shared-models";

// Sync models to your project
const result = await syncModels("./src/models", {
  force: false,
  dryRun: false,
});

// Check for available updates
const updates = await checkUpdates("./src/models");
console.log("Available updates:", updates);

Class-based API (Legacy)

import { ModelManager, ModelSync } from "qclair-shared-models";

const manager = new ModelManager();
const sync = new ModelSync();

// Use the manager
const models = await manager.scanModels();

🔧 CLI Commands

The package includes a powerful CLI tool for managing model synchronization:

Sync Models

# Sync models to current directory
npx qclair-models sync .

# Sync to specific path
npx qclair-models sync ./src/models --models-path custom/path

# Force update (overwrite newer versions)
npx qclair-models sync . --force

# Dry run (preview changes without applying)
npx qclair-models sync . --dry-run

# Combine options
npx qclair-models sync . --force --dry-run

Check for Updates

# Check if model updates are available
npx qclair-models check .

List Available Models

# List all models with metadata
npx qclair-models list

Update Version

# Update the package version metadata
npx qclair-models update-version

📋 Available Models

The package includes the following MongoDB models:

Core Models

• User (UserDocument) - User authentication and profile data
• Enterprise (EnterpriseDocument) - Organization/company data
• Server (ServerDocument) - VPN server configurations
• VPN (VPNDocument) - VPN connection details

Subscription Models

• SubscriptionPlan (SubscriptionPlanDocument) - Available subscription plans
• UserSubscription (UserSubscriptionDocument) - User subscription data
• SubscriptionAuditLog (SubscriptionAuditLogDocument) - Subscription change tracking

Financial Models

• Invoice (InvoiceDocument) - Billing and payment data
• TransactionHistory (TransactionHistoryDocument) - Payment transaction records
• Coupon (CouponDocument) - Discount codes and promotions
• GeoPricing (GeoPricingDocument) - Location-based pricing

System Models

• BetaFeedback (BetaFeedbackDocument) - User feedback collection
• BetaTesters (BetaTestersDocument) - Beta testing program data
• ConnectionHistory (ConnectionHistoryDocument) - VPN connection logs
• LoginHistory (LoginHistoryDocument) - User authentication logs
• Installer (InstallerDocument) - App installer metadata
• StoreLink (StoreLinkDocument) - App store links and metadata
• Webhook (WebhookDocument) - Webhook configuration and logs

⚙️ Integration

In Your package.json

Add sync scripts for easy integration:

{
  "scripts": {
    "models:sync": "qclair-models sync ./src/models",
    "models:check": "qclair-models check ./src/models",
    "prebuild": "npm run models:sync"
  }
}

Git Hooks

Add to .husky/pre-commit or similar:

#!/bin/sh
npx qclair-models check ./src/models

🔒 Configuration

Model Paths

The package automatically detects models in these standard locations:

• src/models
• models
• app/models
• lib/models
• server/models

You can override with the --models-path flag.

Sync Options

interface SyncOptions {
  force: boolean; // Overwrite newer versions
  dryRun: boolean; // Preview changes only
  modelsPath?: string; // Custom models directory
}

🚀 Development

Building the Package

# Install dependencies
npm install

# Build TypeScript
npm run build

# Test the build
npm run build && npx qclair-models list

Publishing Updates

# Update version
npm version patch|minor|major

# Publish to npm
npm publish

📚 API Reference

Functions

• syncModels(targetPath, options) - Sync models to target directory
• checkUpdates(targetPath) - Check for available updates
• scanModels() - Scan and return model metadata
• loadConfig() - Load model configuration
• updateConfig() - Update model configuration

Classes

• ModelManager - Core model management functionality
• ModelSync - Legacy sync operations

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related

• MongoDB Documentation
• Mongoose ODM
• TypeScript Handbook

{
  "scripts": {
    "prebuild": "npx qclair-models sync .",
    "prestart": "npx qclair-models sync .",
    "sync-models": "npx qclair-models sync ."
  }
}

Model Structure

Models should follow this structure:

// @version 1.0.0
import { Schema, model, Document } from "mongoose";

export const version = "1.0.0";

export interface IUser extends Document {
  // ... interface definition
}

const UserSchema = new Schema<IUser>({
  // ... schema definition
});

export const User = model<IUser>("User", UserSchema);
export default User;

License

MIT License - see LICENSE file for details