@rbac/rbac/.kiro/specs/esm-import-fix/requirements.md

Blazing Fast, Zero dependency, Hierarchical Role-Based Access Control for Node.js

# Requirements Document

## Introduction

This specification addresses the ES module import bug in the @rbac/rbac package. Currently, users with ES modules (type: "module" in package.json) cannot import RBAC properly and must use `RBAC.default` instead of just `RBAC`, which breaks TypeScript type checking and creates a poor developer experience. The fix will ensure proper interoperability between CommonJS and ES module consumers while maintaining backward compatibility.

## Glossary

- **Package**: The @rbac/rbac npm package
- **ES_Module_Consumer**: A JavaScript project that uses "type": "module" in package.json
- **CommonJS_Consumer**: A JavaScript project that uses CommonJS module system (default Node.js behavior)
- **Default_Export**: The primary export from a module using `export default`
- **Named_Export**: Additional exports from a module using `export { name }`
- **Exports_Field**: The "exports" field in package.json that defines entry points for different module systems
- **Type_Definitions**: TypeScript .d.ts files that provide type information

## Requirements

### Requirement 1: ES Module Import Support

**User Story:** As a developer using ES modules, I want to import RBAC directly without needing `.default`, so that my code is clean and TypeScript types work correctly.

#### Acceptance Criteria

1. WHEN an ES_Module_Consumer imports RBAC using `import RBAC from '@rbac/rbac'`, THE Package SHALL provide the RBAC function directly without requiring `.default`
2. WHEN an ES_Module_Consumer uses the imported RBAC, THE TypeScript compiler SHALL recognize it as a function with correct type signatures
3. WHEN an ES_Module_Consumer calls the imported RBAC function, THE Package SHALL execute without runtime errors

### Requirement 2: CommonJS Compatibility

**User Story:** As a developer using CommonJS, I want my existing code to continue working without changes, so that upgrading the package doesn't break my application.

#### Acceptance Criteria

1. WHEN a CommonJS_Consumer imports RBAC using `const RBAC = require('@rbac/rbac')`, THE Package SHALL provide the RBAC function directly
2. WHEN a CommonJS_Consumer uses `require('@rbac/rbac').default`, THE Package SHALL continue to support this pattern for backward compatibility
3. WHEN a CommonJS_Consumer upgrades to the fixed version, THE Package SHALL maintain identical runtime behavior

### Requirement 3: Package Configuration

**User Story:** As a package maintainer, I want proper package.json configuration, so that module bundlers and Node.js can resolve the correct entry points.

#### Acceptance Criteria

1. THE Package SHALL define an Exports_Field in package.json that specifies entry points for both CommonJS and ES modules
2. THE Package SHALL maintain the "main" field for backward compatibility with older tools
3. THE Package SHALL specify Type_Definitions paths for both module systems in the Exports_Field
4. WHERE TypeScript is used, THE Package SHALL ensure Type_Definitions are correctly resolved for both module systems

### Requirement 4: Named Exports Preservation

**User Story:** As a developer, I want to continue using named exports like `createTenantRBAC`, so that I can access all package functionality.

#### Acceptance Criteria

1. WHEN a consumer imports Named_Exports using `import { createTenantRBAC } from '@rbac/rbac'`, THE Package SHALL provide these exports correctly
2. THE Package SHALL maintain all existing Named_Exports without changes
3. THE Type_Definitions SHALL correctly reflect all Named_Exports for TypeScript consumers

### Requirement 5: Build Output Structure

**User Story:** As a package maintainer, I want a clear build output structure, so that the package is maintainable and debuggable.

#### Acceptance Criteria

1. THE Package SHALL compile TypeScript source to CommonJS format in the lib directory
2. THE Package SHALL generate Type_Definitions alongside compiled JavaScript files
3. THE Package SHALL maintain the current directory structure (src → lib) for consistency
4. WHEN the build process completes, THE Package SHALL contain all necessary files for both module systems

### Requirement 6: Type Safety

**User Story:** As a TypeScript developer, I want accurate type checking, so that I can catch errors at compile time.

#### Acceptance Criteria

1. WHEN a TypeScript consumer imports the Default_Export, THE Type_Definitions SHALL correctly type it as the RBAC function
2. WHEN a TypeScript consumer imports Named_Exports, THE Type_Definitions SHALL provide accurate types for each export
3. THE Type_Definitions SHALL not require consumers to use `.default` to access correct types
4. IF a consumer uses incorrect import syntax, THE TypeScript compiler SHALL provide clear error messages