Skip to content

Versioning ​

RBAC Evolution follows semantic versioning. From 1.0 on, this page is the promise: what a patch, minor or major release can change, what is supported, and how deprecations work.

What each release can change ​

ReleaseCanCannot
Patch (1.2.3 → 1.2.4)Fix bugs, docs and types that were wrongChange working behaviour on purpose
Minor (1.2 → 1.3)Add exports, options (with a default that keeps the old behaviour), optional adapter methods, support for new runtime or framework versionsRemove or rename anything, change a default
Major (1.x → 2.0)Anything above, listed in the upgrade guide—

Some details:

  • Security fixes are patches, even when a check that wrongly allowed now denies. A fix that makes a check allow where it wrongly denied is a patch too, and is called out in the changelog.
  • All packages share one version number. 1.x of one package works with 1.x of every other.
  • Types are public API. A type change that breaks correct code is a major change. Types that only describe code that already failed at runtime can be tightened in a minor (for example, a guard called with no names).
  • Not covered: members marked @internal, unexported types, the exact wording of error messages, and anything under a /testing entry point beyond runAdapterTests.

What 1.0 freezes ​

These only change in a major release:

  • Every export of every package. The list is checked in CI against etc/*.api.md, so any change shows up in review.
  • The RbacErrorCode values: PERMISSION_DOES_NOT_EXIST, PERMISSION_ALREADY_EXISTS, ROLE_DOES_NOT_EXIST, ROLE_ALREADY_EXISTS, GUARD_DOES_NOT_MATCH, TEAM_DOES_NOT_MATCH, TEAMS_NOT_ENABLED, INVALID_NAME, INVALID_WILDCARD_PERMISSION, INVALID_SYNC_DEFINITION. New codes can be added in a minor.
  • The 401/403 JSON body of the integrations: error, reason, message, and required (only with exposeRequirements: true).
  • The event names (role.attached, role.detached, permission.attached, permission.detached, role.created, role.deleted, permission.created, permission.deleted) and their payload fields. New fields can be added in a minor.
  • The defaults: cache on with MemoryCache (10 000 entries) and a 1-day TTL, wildcard: false, teams: false, default guard web.
  • The naming of guards and options, which follows spatie:
    • requirePermission / requireRole / requireRoleOrPermission in every integration. NestJS uses decorators in the plural (@RequirePermissions, @RequireRoles), as Nest decorators usually are.
    • Permission guards take { any: true } (default: all of them); role guards take { all: true } (default: any of them), like spatie's middleware.
    • hasRole and hasAnyRole are both kept, as in spatie.

Custom adapters ​

RbacAdapter is the contract for your own storage. In 1.x:

  • New methods are optional, with a fallback in the engine, so existing adapters keep working.
  • A new required method is a major change.
  • The conformance suite (runAdapterTests) can gain tests in a minor. They only check behaviour the contract already describes, such as exact name matching, so a correct adapter keeps passing.

Support ​

AreaSupported in 1.x
Node.js20, 22, 24
Bunlatest
Denonot supported
PostgreSQL13+
MySQL / MariaDB8 / 10.6+
SQLite3.35+
SQL Server2019+
MongoDB6+
TypeScript5.0+, with moduleResolution set to node16, nodenext or bundler
Framework or ORMSupported in 1.x
Express4, 5
Fastify5
Hono4
Next.js14, 15, 16
Nuxt3, 4
NestJS10, 11, 12
React18, 19
Vue3.3+
Prisma5.12+, 6
Drizzle ORM0.38+
Kysely0.28
Mongoose8

These match each package's peerDependencies. CI tests the oldest and the newest supported version of each one (the peers job). See the test report.

TypeScript's legacy moduleResolution: "node" (node10) ignores the exports field. The main entry point of each package still resolves there, but subpaths such as /testing, /pg or /middleware don't. It is not supported.

When support changes ​

  • Dropping a Node.js version is a major change.
  • Raising the minimum version of a peer dependency is a major change, unless that version has reached its end of life upstream. Then it can happen in a minor, with a note in the changelog.
  • Adding support for a new Node.js, database or framework version is a minor change.

Deprecations ​

  • A deprecated API keeps working for at least one minor release. It is removed only in the next major.
  • It is marked @deprecated in the types (your editor strikes it through), and logs a one-time warning when NODE_ENV is development.
  • Every deprecation is listed in the changelog and in the upgrade guide.

Security fixes ​

The latest 1.x minor gets security fixes. After 1.0 ships, 0.x gets fixes for critical issues for three months. See the security policy.

Released under the MIT License. Inspired by spatie/laravel-permission.