Sequelize Guard

A powerful, type-safe authorization library for Sequelize.js

About

SequelizeGuard is a comprehensive authorization library for Sequelize.js that provides a robust, performant, and easy-to-use role-based access control (RBAC) system. Built with TypeScript and modern tooling, it enables you to manage complex permission structures with a clean, fluent API.

✨ What's New in v6

Sequelize Guard v6 is a complete rewrite with major improvements:

• 🎯 Full TypeScript Support - Complete rewrite in TypeScript with full type definitions
• � Sequelize 6 Compatible - Updated to work with Sequelize v6.x
• � ESM & CommonJS - Dual package support for modern and legacy projects
• 🏗️ Modern Tooling - Built with Vite, tested with Vitest
• � Better Type Safety - Enhanced IntelliSense and compile-time checking
• ⚡ 99% Backward Compatible - Minimal breaking changes from v5.x

Upgrading from v5? Check out the Migration Guide for a smooth transition.

Features

• 🚀 Fast & Efficient - Cache-based permission resolution for optimal performance
• 🎯 Intuitive API - Fluent, semantic API that reads like natural language
• 🔐 Flexible RBAC - Assign multiple roles and permissions to users
• 📊 Event-Driven - Listen for authorization events for logging and auditing
• 💾 Smart Caching - Configurable user permission caching
• 🛡️ Safe Operations - Built-in safeguards for role and permission deletions

Installation

# npm
npm install sequelize-guard sequelize

# yarn
yarn add sequelize-guard sequelize

# pnpm
pnpm add sequelize-guard sequelize

Requirements:

• Node.js ≥ 20.19.0
• Sequelize ≥ 6.37.7

Quick Start

import { Sequelize } from 'sequelize';
import SequelizeGuard from 'sequelize-guard';

const sequelize = new Sequelize(/* config */);
const guard = new SequelizeGuard(sequelize);

// Assign roles and permissions
await user.assignRole('admin');
await guard.allow('admin', ['view', 'edit'], 'blog');

// Check permissions
const canEdit = await user.can('edit blog');
const isAdmin = await user.isA('admin');

Note: Works with both TypeScript and JavaScript (ESM/CommonJS). See documentation for JavaScript examples.

Documentation

For comprehensive guides, API reference, and examples, visit our documentation:

📖 https://sequelize-guard.js.org

📖 (Fallback: https://sequelize-guard.vercel.app)

Key Topics

• Getting Started - Installation and basic setup
• API Reference - Complete API documentation
• TypeScript Support - Using with TypeScript
• Examples - Real-world usage examples

Migration

• Migration Guide to v6 - Complete guide for upgrading to v6

Core Concepts

Permission Checks

// Check specific permission
await user.can('edit blog');

// Check wildcard permissions
await user.can('* blog'); // All actions on blog
await user.can('view *'); // View all resources
await user.can('*'); // Superadmin - all actions on all resources

Role Checks

// Check single role
await user.isA('admin');
await user.isAn('editor');

// Check multiple roles
await user.isAnyOf(['admin', 'moderator']); // Has any of these roles
await user.isAllOf(['user', 'verified']); // Has all of these roles

Assigning Permissions

// Fluent API
await guard
  .init()
  .allow('admin')
  .to(['view', 'edit', 'delete'])
  .on('blog')
  .commit();

// One-liner
await guard.allow('admin', ['view', 'edit'], 'blog');

For more details, visit the full documentation.

Contributing

We love contributions! SequelizeGuard is open source and we welcome contributions of all kinds:

• 🐛 Bug fixes
• ✨ New features
• 📝 Documentation improvements
• ✅ Test coverage improvements
• 💡 Ideas and suggestions

# Clone the repository
git clone https://github.com/lotivo/sequelize-guard.git
cd sequelize-guard

# Install dependencies
yarn install

# Run tests
yarn test

# Build
yarn build

Documentation

Generating API Documentation

API documentation is automatically generated from TypeScript source code:

# Generate API docs manually
yarn docs:generate

The API documentation is automatically updated after each release via GitHub Actions. See scripts/README.md for details.

Reporting Issues

Found a bug or have a feature request? Open an issue with:

• Clear description
• Steps to reproduce (for bugs)
• Your environment (Node, Sequelize, sequelize-guard versions)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Influences

• Spatie's Laravel-permission - Authorization library for Laravel
• Node-ACL - Access Control List for Node.js

Alternatives

• Node-ACL - A versatile library with support for most ORMs
• AccessControl - Role and attribute-based access control
• CASL - Isomorphic authorization library

Support

Need help? Here's how to get support:

• 📖 Documentation: https://sequelize-guard.js.org (or https://sequelize-guard.vercel.app)
• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions

Created by Pankaj Vaghela for Open Source Community.

If you find this project helpful, please consider giving it a ⭐️!