npm package: @pnkx-lib/core
Description: Core utilities and hooks for PNKX UI library with optimized tree shaking support.
Latest version: 1.1.237

# @pnkx-lib/core

Core utilities and hooks for PNKX UI library with optimized tree shaking support.

## 🎯 Features

- **Tree Shakable**: Import only what you need for optimal bundle size
- **TypeScript Support**: Full TypeScript definitions with modular exports
- **React Hooks**: Reusable hooks for common patterns
- **HTTP Services**: Configured HTTP client with error handling
- **Constants & Utilities**: Shared constants and utility functions

## 📦 Installation

```bash
npm install @pnkx-lib/core
# or
pnpm add @pnkx-lib/core
```

## 🚀 Usage

### Individual Module Imports (Recommended for Tree Shaking)

```typescript
// Import specific hooks (small bundle size)
import { useToggle } from '@pnkx-lib/core/hooks/useToggle';
import { useErrorHandler } from '@pnkx-lib/core/hooks/useErrorHandler';

// Import specific constants  
import { CategoryActionCode } from '@pnkx-lib/core/constants/bulkAction';
import { STORAGE_KEYS } from '@pnkx-lib/core/constants/storage';

// Import specific error constants
import { CommonErrorCodes } from '@pnkx-lib/core/constants/error/errorCodeConstants';
import { COMMON_ERROR_CODES, ALL_ERROR_CODES } from '@pnkx-lib/core/constants/error/errorCodes';

// Import specific services
import { httpService } from '@pnkx-lib/core/services/httpService';

// Import specific types
import type { InitialFiltersSearch, PaginationFilters } from '@pnkx-lib/core/interface/filters';
```

### Bundle Index Imports (Less Optimal)

```typescript
// Imports entire module - larger bundle size
import { useToggle } from '@pnkx-lib/core/hooks';
import { CategoryActionCode } from '@pnkx-lib/core/constants';
```

## 📊 Module Sizes (Tree Shaking Benefits)

| Module | Size | Description |
|--------|------|-------------|
| `hooks/useToggle` | 413 bytes | Simple toggle hook |
| `hooks/useErrorHandler` | 2.43 KB | Error handling hook |
| `hooks/useHandleBulkAction` | 2.03 KB | Bulk action handler |
| `constants/bulkAction` | 1.77 KB | Action constants |
| `constants/storage` | 111 bytes | Storage keys |
| `constants/error/errorCodeConstants` | 6.67 KB | Error code constants |
| `constants/error/errorCodes` | 18.89 KB | All error messages |
| `hooks/useFiltersHandler` | 96.6 KB | Complex filter handler |
| `services/httpService` | 98.2 KB | HTTP service with Axios |

**🎯 Tree Shaking Benefit**: Import only what you need! A simple app using just `useToggle` and `CategoryActionCode` will bundle only ~2.2KB instead of ~200KB.

## 🔧 Available Modules

### Hooks
- `useToggle` - Simple boolean state toggle
- `useErrorHandler` - Global error handling
- `useHandleBulkAction` - Bulk operations handler  
- `useFiltersHandler` - Complex filtering and pagination

### Services
- `httpService` - Configured Axios instance
- `errorHandlerService` - Error handling service

### Constants
- `bulkAction` - Action codes and messages
- `storage` - Storage keys
- `statusConfig` - Status configurations
- `error` - Error code constants

### Utils
- `bulkActionUtils` - Bulk action utilities

### Types/Interfaces
- `filters` - Filter and pagination types
- `bulkAction` - Bulk action types
- `errorHandling` - Error handling types

## 📖 Documentation

- [Tree Shaking Guide](./CORE_TREE_SHAKING.md) - Detailed tree shaking optimization
- [Bulk Action Refactor](./BULK_ACTION_REFACTOR.md) - Bulk action improvements

## 🧪 Testing Tree Shaking

```bash
# Test tree shaking
cd examples
node tree-shaking-test.js
```

## 🔧 Troubleshooting

### Consumer Project Issues

If you're having issues in your project, you can use our troubleshooting script:

```bash
# Download and run troubleshooting script
curl -o troubleshoot.sh https://raw.githubusercontent.com/your-org/pnkx-ui/main/packages/core/scripts/troubleshoot-consumer.sh
chmod +x troubleshoot.sh
./troubleshoot.sh
```

Or copy the script from `packages/core/scripts/troubleshoot-consumer.sh` and run it in your project directory.

### TypeScript Declaration Errors

If you encounter TypeScript errors like:
```
Could not find a declaration file for module '@pnkx-lib/core'
```

**Solutions:**

1. **Update to latest version:**
   ```bash
   npm install @pnkx-lib/core@latest
   ```

2. **Clear cache and reinstall:**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

3. **Check TypeScript configuration:**
   ```json
   // tsconfig.json
   {
     "compilerOptions": {
       "moduleResolution": "bundler", // or "node"
       "allowSyntheticDefaultImports": true,
       "esModuleInterop": true
     }
   }
   ```

4. **Verify import paths:**
   ```typescript
   // ✅ Correct
   import { useToggle } from '@pnkx-lib/core/hooks/useToggle';
   
   // ❌ May cause issues in some setups
   import { useToggle } from '@pnkx-lib/core';
   ```

### Bundle Size Issues

If your bundle is too large:

1. **Use individual imports** instead of index imports
2. **Check which modules you're importing** - some are large (useFiltersHandler: 96KB)
3. **Use dynamic imports** for heavy modules when possible

### Performance Issues

1. **Avoid importing unused modules**
2. **Use tree shaking verification** tools
3. **Monitor bundle analyzer** output

---

**Built with tree shaking optimization for minimal bundle impact** 🚀

## Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:

```js
export default tseslint.config({
  extends: [
    // Remove ...tseslint.configs.recommended and replace with this
    ...tseslint.configs.recommendedTypeChecked,
    // Alternatively, use this for stricter rules
    ...tseslint.configs.strictTypeChecked,
    // Optionally, add this for stylistic rules
    ...tseslint.configs.stylisticTypeChecked,
  ],
  languageOptions: {
    // other options...
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
})
```

You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:

```js
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config({
  plugins: {
    // Add the react-x and react-dom plugins
    'react-x': reactX,
    'react-dom': reactDom,
  },
  rules: {
    // other rules...
    // Enable its recommended typescript rules
    ...reactX.configs['recommended-typescript'].rules,
    ...reactDom.configs.recommended.rules,
  },
})
```

## 🔧 Troubleshooting

### Consumer Project Issues

If you're having issues in your project, you can use our troubleshooting script:

```bash
# Download and run troubleshooting script
curl -o troubleshoot.sh https://raw.githubusercontent.com/your-org/pnkx-ui/main/packages/core/scripts/troubleshoot-consumer.sh
chmod +x troubleshoot.sh
./troubleshoot.sh
```

Or copy the script from `packages/core/scripts/troubleshoot-consumer.sh` and run it in your project directory.

### TypeScript Declaration Errors

If you encounter TypeScript errors like:
```
Could not find a declaration file for module '@pnkx-lib/core'
```

**Solutions:**

1. **Update to latest version:**
   ```bash
   npm install @pnkx-lib/core@latest
   ```

2. **Clear cache and reinstall:**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

3. **Check TypeScript configuration:**
   ```json
   // tsconfig.json
   {
     "compilerOptions": {
       "moduleResolution": "bundler", // or "node"
       "allowSyntheticDefaultImports": true,
       "esModuleInterop": true
     }
   }
   ```

4. **Verify import paths:**
   ```typescript
   // ✅ Correct
   import { useToggle } from '@pnkx-lib/core/hooks/useToggle';
   
   // ❌ May cause issues in some setups
   import { useToggle } from '@pnkx-lib/core';
   ```

### Bundle Size Issues

If your bundle is too large:

1. **Use individual imports** instead of index imports
2. **Check which modules you're importing** - some are large (useFiltersHandler: 96KB)
3. **Use dynamic imports** for heavy modules when possible

### Performance Issues

1. **Avoid importing unused modules**
2. **Use tree shaking verification** tools
3. **Monitor bundle analyzer** output

---

**Built with tree shaking optimization for minimal bundle impact** 🚀