@rbac/rbac

# Implementation Plan: ES Module Import Fix ## Overview This implementation plan addresses the ES module import bug by updating the package.json configuration to properly support both CommonJS and ES module consumers. The fix involves adding the "exports" field with appropriate conditional exports, ensuring TypeScript type definitions are correctly resolved, and validating the changes work across different module systems and Node.js versions. ## Tasks - [x] 1. Update package.json with exports field configuration - Add "exports" field with conditional exports for import/require/types/default - Maintain existing "main" and "types" fields for backward compatibility - Ensure all paths point to correct files in lib/ directory - _Requirements: 3.1, 3.2, 3.3_ - [ ]* 2. Create test infrastructure for module system validation - Set up test directories for CommonJS and ES module test projects - Create helper functions to generate test projects with different configurations - Implement cleanup utilities for temporary test projects - _Requirements: 1.1, 2.1_ - [ ] 3. Implement ES module import validation - [x] 3.1 Create test ES module project with type: "module" - Generate package.json with "type": "module" - Create test file that imports RBAC default export - Verify imported RBAC is a function (not object with .default) - _Requirements: 1.1_ - [ ]* 3.2 Write property test for ES module default import - **Property 1: Default Import Provides Function Directly** - **Validates: Requirements 1.1, 1.3, 2.1** - Generate multiple ES module test projects with different Node.js versions - Verify default import provides function directly in all cases - [x] 3.3 Create TypeScript ES module test project - Generate tsconfig.json with "module": "ES2020" or "ESNext" - Create TypeScript file importing RBAC with type annotations - Run tsc to verify no type errors occur - _Requirements: 1.2_ - [ ]* 3.4 Write property test for TypeScript type resolution - **Property 2: TypeScript Type Resolution for Default Import** - **Validates: Requirements 1.2, 6.1, 6.3** - Generate TypeScript projects with different module configurations - Verify type checking passes without requiring .default accessor - [ ] 4. Implement CommonJS compatibility validation - [x] 4.1 Create test CommonJS project - Generate package.json without "type" field (default CommonJS) - Create test file that requires RBAC - Verify required RBAC is a function - _Requirements: 2.1_ - [x] 4.2 Test backward compatibility with .default accessor - Create test file using require('@rbac/rbac').default - Verify it returns the same function as direct require - Test that both patterns work identically - _Requirements: 2.2_ - [ ]* 4.3 Write property test for backward compatibility - **Property 4: Backward Compatibility for .default Accessor** - **Validates: Requirements 2.2** - Verify both require patterns return identical functions - [x] 5. Checkpoint - Verify basic import functionality - Run all import tests for both CommonJS and ES modules - Ensure default imports work correctly in both systems - Ensure all tests pass, ask the user if questions arise. - [ ] 7. Validate build output and structure - [ ] 7.1 Verify TypeScript compilation output - Run npm run build - Check that lib/ directory contains .js files in CommonJS format - Verify files contain exports.default and exports.X patterns - _Requirements: 5.1_ - [ ] 7.2 Verify type definition generation - Check that .d.ts files exist alongside .js files - Verify type definitions contain correct export declarations - _Requirements: 5.2_ - [ ] 7.3 Verify directory structure consistency - Confirm src/ to lib/ mapping is maintained - Check that all source files have corresponding output files - _Requirements: 5.3, 5.4_ - [-] 8. Implement comprehensive TypeScript type checking tests - [x] 8.1 Create TypeScript test for default export usage - Write TypeScript code using RBAC as a function - Call RBAC with configuration and role definitions - Verify tsc compiles without errors - _Requirements: 6.1_ - [x] 8.2 Create TypeScript test for named exports usage - Write TypeScript code using createTenantRBAC - Use proper type annotations for parameters - Verify tsc compiles without errors - _Requirements: 6.2_ - [ ]* 8.3 Write property test for TypeScript module resolution - **Property 5: TypeScript Module Resolution** - **Validates: Requirements 3.4** - Generate TypeScript projects with different tsconfig.json settings - Verify type resolution works for both default and named imports - [ ] 9. Checkpoint - Run full test suite - Execute all property tests (minimum 100 iterations each) - Run all unit tests for specific scenarios - Verify existing package tests still pass - Ensure all tests pass, ask the user if questions arise. - [x] 11. Documentation and validation - [x] 11.1 Update README with import examples - Add ES module import example - Add CommonJS import example - Show both default and named export usage - _Requirements: 1.1, 2.1, 4.1_ - [x] 11.2 Verify package.json is valid - Run npm pack to create tarball - Test installation from tarball in fresh project - Verify imports work from installed package - _Requirements: 3.1, 3.2, 3.3_ - [x] 12. Final checkpoint - Complete validation - Run complete test suite one final time - Verify all requirements are met - Ensure backward compatibility is maintained - Ensure all tests pass, ask the user if questions arise. ## Notes - Tasks marked with `*` are optional and can be skipped for faster MVP - Each task references specific requirements for traceability - Property tests should run minimum 100 iterations to ensure comprehensive coverage - The fix requires no changes to source code, only package.json configuration - Existing tests should continue to pass without modification - Focus on validation and testing since the fix is configuration-only