test: Add comprehensive module import tests for CJS and ESM

- Add CommonJS test suite validating direct require() without .default accessor
- Add ES modules test suite with named exports and workaround patterns
- Add TypeScript ES modules test suite with compiled output validation
- Add import documentation to README with examples for both module systems
- Update package.json with conditional exports for require and import paths
- Update .gitignore to exclude .kiro build artifacts
- Bump version to 2.1.2 to reflect module system improvements
- Ensure backward compatibility with .default accessor pattern
- Validate named exports accessibility across all module systems

Author: phellipeandrade

.gitignore

@@ -1,7 +1,7 @@
 # Logs
 logs
 *.log
-
+.kiro
 # Runtime data
 pids
 *.pid

README.md

@@ -43,6 +43,38 @@
 This library is written in TypeScript and the published package ships with
 its declaration files for a great developer experience.
 
+#### Import
+
+The package supports both ES modules and CommonJS.
+
+**ES Modules (recommended)**
+
+```ts
+// Default import
+import RBAC from '@rbac/rbac';
+
+// Named imports
+import { createTenantRBAC, MongoRoleAdapter } from '@rbac/rbac';
+
+// Combined
+import RBAC, { createTenantRBAC } from '@rbac/rbac';
+```
+
+**CommonJS**
+
+```js
+// Default import
+const RBAC = require('@rbac/rbac');
+
+// Named imports
+const { createTenantRBAC, MongoRoleAdapter } = require('@rbac/rbac');
+
+// Combined
+const RBAC = require('@rbac/rbac');
+const { createTenantRBAC } = require('@rbac/rbac');
+```
+
+#### Usage
 
 RBAC is a curried function thats initially takes an object with configurations, 
 then returns another function that takes an object with roles, 

package.json

@@ -1,9 +1,17 @@
 {
   "name": "@rbac/rbac",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Blazing Fast, Zero dependency, Hierarchical Role-Based Access Control for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.mjs",
+      "require": "./lib/index.cjs",
+      "default": "./lib/index.js"
+    }
+  },
   "scripts": {
     "build": "tsc && vite build",
     "dev": "tsc -w",

test/cjs-test/README.md

@@ -0,0 +1,82 @@
+# CommonJS Import Test
+
+This test project validates CommonJS import behavior for the @rbac/rbac package.
+
+## Purpose
+
+This test validates **Requirement 2.1**: CommonJS consumers should be able to import RBAC directly without needing `.default` accessor.
+
+## Test Files
+
+### index.js
+The main test file that validates the expected behavior:
+- Imports RBAC using CommonJS syntax: `const RBAC = require('@rbac/rbac')`
+- Verifies RBAC is imported as a function directly (not an object requiring .default)
+- Tests basic RBAC functionality including permissions
+
+### test-backward-compat.js
+Validates backward compatibility with the `.default` accessor pattern:
+- Uses `require('@rbac/rbac').default` to access the function
+- Verifies this pattern still works for existing code
+- Validates **Requirement 2.2**: Backward compatibility
+
+### test-named-exports.js
+Validates that named exports are accessible in CommonJS:
+- Tests destructuring: `const { createTenantRBAC } = require('@rbac/rbac')`
+- Verifies named exports are accessible on the default export
+- Validates **Requirement 4.1**: Named exports preservation
+
+## Running Tests
+
+```bash
+# Install dependencies
+npm install
+
+# Run the main test
+npm test
+
+# Run backward compatibility test
+node test-backward-compat.js
+
+# Run named exports test
+node test-named-exports.js
+
+# Run all tests
+npm test && node test-backward-compat.js && node test-named-exports.js
+```
+
+## Package Configuration
+
+The package.json includes:
+- No `"type"` field - Uses default CommonJS mode
+- `"@rbac/rbac": "file:../../"` - Links to the local package for testing
+
+## Implementation Details
+
+The fix uses a CommonJS wrapper file (`lib/index.cjs`) that:
+1. Imports the compiled TypeScript output (`lib/index.js`)
+2. Exports the default export as the main `module.exports`
+3. Preserves all named exports
+4. Maintains the `.default` accessor for backward compatibility
+
+The package.json `exports` field uses conditional exports:
+```json
+{
+  "exports": {
+    ".": {
+      "require": "./lib/index.cjs",
+      "import": "./lib/index.mjs"
+    }
+  }
+}
+```
+
+This ensures CommonJS consumers get the wrapper that provides direct function access.
+
+## Test Results
+
+All tests pass, confirming:
+- ✅ Direct require works: `require('@rbac/rbac')` returns function
+- ✅ Backward compatibility: `require('@rbac/rbac').default` still works
+- ✅ Named exports: `require('@rbac/rbac').createTenantRBAC` works
+- ✅ Destructuring: `const { createTenantRBAC } = require('@rbac/rbac')` works

test/cjs-test/index.js

@@ -0,0 +1,46 @@
+const assert = require('assert');
+
+// Test Requirement 2.1: CommonJS consumer should be able to require RBAC directly
+// without needing .default accessor
+const RBAC = require('@rbac/rbac');
+
+console.log('Testing CommonJS import without .default accessor...');
+
+// Verify that RBAC is a function directly
+assert.strictEqual(typeof RBAC, 'function', 'RBAC should be a function when imported via require()');
+
+console.log('✅ Type check passed: RBAC is a function');
+
+// Test that we can actually use it
+const roles = {
+  user: {
+    can: ['read']
+  },
+  admin: {
+    can: ['read', 'write']
+  }
+};
+
+const rbacInstance = RBAC({ enableLogger: false })(roles);
+
+assert.strictEqual(typeof rbacInstance, 'object', 'RBAC() should return an object');
+assert.strictEqual(typeof rbacInstance.can, 'function', 'RBAC instance should have a can method');
+
+console.log('✅ Functional check passed: RBAC works correctly');
+
+// Test basic permission check
+(async () => {
+  try {
+    const canRead = await rbacInstance.can('user', 'read');
+    assert.strictEqual(canRead, true, 'User should be able to read');
+    
+    const canWrite = await rbacInstance.can('user', 'write');
+    assert.strictEqual(canWrite, false, 'User should not be able to write');
+    
+    console.log('✅ Permission checks passed');
+    console.log('✅ All CommonJS tests passed successfully!');
+  } catch (error) {
+    console.error('❌ Test failed:', error.message);
+    process.exit(1);
+  }
+})();

test/cjs-test/package-lock.json

@@ -0,0 +1,12 @@
+{
+  "name": "rbac-cjs-test",
+  "version": "1.0.0",
+  "description": "Test CommonJS import without .default accessor",
+  "main": "index.js",
+  "scripts": {
+    "test": "node index.js && node test-backward-compat.js && node test-named-exports.js"
+  },
+  "dependencies": {
+    "@rbac/rbac": "file:../../"
+  }
+}

test/cjs-test/package.json

@@ -0,0 +1,69 @@
+const assert = require('assert');
+
+// Test Requirement 2.2: Backward compatibility with .default accessor
+// Both require('@rbac/rbac') and require('@rbac/rbac').default should work identically
+
+console.log('Testing backward compatibility with .default accessor...');
+
+// Import using both patterns
+const RBACDirect = require('@rbac/rbac');
+const RBACWithDefault = require('@rbac/rbac').default;
+
+// Verify both are functions
+assert.strictEqual(typeof RBACDirect, 'function', 'require("@rbac/rbac") should be a function');
+assert.strictEqual(typeof RBACWithDefault, 'function', 'require("@rbac/rbac").default should be a function');
+
+console.log('✅ Type check passed: Both patterns return functions');
+
+// Verify they return the SAME function (reference equality)
+assert.strictEqual(RBACDirect, RBACWithDefault, 
+  'require("@rbac/rbac") and require("@rbac/rbac").default should return the same function');
+
+console.log('✅ Identity check passed: Both patterns return the same function reference');
+
+// Test that both patterns work identically with the same input
+const roles = {
+  user: {
+    can: ['read']
+  },
+  admin: {
+    can: ['read', 'write']
+  }
+};
+
+const rbacInstance1 = RBACDirect({ enableLogger: false })(roles);
+const rbacInstance2 = RBACWithDefault({ enableLogger: false })(roles);
+
+assert.strictEqual(typeof rbacInstance1, 'object', 'RBACDirect() should return an object');
+assert.strictEqual(typeof rbacInstance1.can, 'function', 'RBACDirect instance should have a can method');
+
+assert.strictEqual(typeof rbacInstance2, 'object', 'RBACWithDefault() should return an object');
+assert.strictEqual(typeof rbacInstance2.can, 'function', 'RBACWithDefault instance should have a can method');
+
+console.log('✅ Functional check passed: Both patterns create valid RBAC instances');
+
+// Test that both instances behave identically
+(async () => {
+  try {
+    const canRead1 = await rbacInstance1.can('user', 'read');
+    const canRead2 = await rbacInstance2.can('user', 'read');
+    assert.strictEqual(canRead1, canRead2, 'Both instances should return same result for user read permission');
+    assert.strictEqual(canRead1, true, 'User should be able to read');
+    
+    const canWrite1 = await rbacInstance1.can('user', 'write');
+    const canWrite2 = await rbacInstance2.can('user', 'write');
+    assert.strictEqual(canWrite1, canWrite2, 'Both instances should return same result for user write permission');
+    assert.strictEqual(canWrite1, false, 'User should not be able to write');
+    
+    const canWriteAdmin1 = await rbacInstance1.can('admin', 'write');
+    const canWriteAdmin2 = await rbacInstance2.can('admin', 'write');
+    assert.strictEqual(canWriteAdmin1, canWriteAdmin2, 'Both instances should return same result for admin write permission');
+    assert.strictEqual(canWriteAdmin1, true, 'Admin should be able to write');
+    
+    console.log('✅ Behavior check passed: Both patterns produce identical results');
+    console.log('✅ All backward compatibility tests passed successfully!');
+  } catch (error) {
+    console.error('❌ Test failed:', error.message);
+    process.exit(1);
+  }
+})();

test/cjs-test/test-backward-compat.js

@@ -0,0 +1,19 @@
+const assert = require('assert');
+
+// Test that named exports are accessible
+const { createTenantRBAC } = require('@rbac/rbac');
+
+console.log('Testing named exports in CommonJS...');
+
+// Verify that createTenantRBAC is a function
+assert.strictEqual(typeof createTenantRBAC, 'function', 'createTenantRBAC should be a function');
+
+console.log('✅ Named export check passed: createTenantRBAC is accessible');
+
+// Also verify we can get both default and named exports together
+const RBAC = require('@rbac/rbac');
+assert.strictEqual(typeof RBAC, 'function', 'Default export should be a function');
+assert.strictEqual(typeof RBAC.createTenantRBAC, 'function', 'Named export should be accessible on default export');
+
+console.log('✅ Combined export check passed');
+console.log('✅ All named export tests passed!');