feat: group Versioning, Automatic Bit Calculation and Permission Migration Support

[productdevbook]

wait pr: #10

close: #11

1. Group Versioning and Deprecation

• Added metadata to groups including version info (since), deprecation status (deprecated), and suggested alternatives (replacedBy)
• Implemented a warning mechanism when accessing deprecated groups
• Created easy deprecation of groups with the deprecateGroup() method
• Added tracking of deprecation time with deprecatedSince property

2. Automatic Bit Calculation

• System now automatically calculates required bits based on permission values
• Added warnings and auto-adjustment when specified bit count is insufficient
• Eliminated the need to manually specify bit count in most cases
• Ensures optimal memory usage while preserving all permission values

3. Permission Migration System

• Implemented automatic migration from deprecated groups to new groups
• Added autoMigrate option to seamlessly handle deprecated permissions
• Created permission mapping to transform old permissions to new permissions
• Maintained backward compatibility while allowing schema evolution

4. Technical Improvements

• Enhanced type safety for all APIs
• Added full TypeScript generics support
• Improved error messages and warnings
• Created comprehensive test suite for new features

Usage Examples

Group Versioning and Deprecation

// Define groups with version information
permask.defineGroup('DOCUMENTS', 2, { since: '1.0.0' })
       .defineGroup('FILES', 3, { since: '2.0.0' })
       .deprecateGroup('DOCUMENTS', { 
         replacedBy: 'FILES',
         version: '2.0.0',
         message: 'DOCUMENTS group is deprecated, use FILES instead'
       });

// Check if a group is deprecated
if (permask.isGroupDeprecated('DOCUMENTS')) {
  // Handle deprecated group
}

// Display deprecation warnings automatically
permask.check(userPermission, { warnOnDeprecated: true });

// Get detailed deprecation information
const info = permask.getGroupDeprecationInfo('DOCUMENTS');
console.log(info.replacedBy);  // 'FILES'
console.log(info.deprecatedSince); // '2.0.0'

Automatic Bit Calculation

// No need to specify accessBits - automatically calculated based on values
const permask = new PermaskBuilder({
  permissions: {
    VIEW: 1,
    EDIT: 2,
    DELETE: 4,
    SHARE: 8,
    PRINT: 16,
    APPROVE: 32  // Requires 6 bits
  }
}).build();

// System automatically uses 6 bits to accommodate all permissions
// You can still specify accessBits if you want more control
const customPermask = new PermaskBuilder({
  permissions: {
    VIEW: 1,
    EDIT: 2,
  },
  accessBits: 8  // Explicitly use 8 bits for future expansion
}).build();

Benefits

Future-Proofing: Safely evolve your permission schema while maintaining backward compatibility

Usability: Makes the API easier to use with sensible defaults and automatic calculations

Maintainability: Clear deprecation paths and migration strategies for permissions
Type Safety: Full TypeScript support for all new features

Resource Efficiency: Automatically optimizes bit usage based on actual permission values