@bluefly/shared v0.1.1

@bluefly/shared

A shared package of components, utilities, and services used across multiple packages in the Bluefly ecosystem.

Installation

For production use

npm install @bluefly/shared

For local development

For local development, you can use npm link:

# In the shared package directory
cd /path/to/bfcli/shared
npm link

# In the project that will use the shared package
cd /path/to/your-project
npm link @bluefly/shared

This creates a symbolic link from your project's node_modules/@bluefly/shared to the local shared package.

Directory Structure

• config/ - Configuration management system
• constants/ - Shared constants and enums
• interfaces/ - TypeScript interfaces and types
• services/ - Shared services (HTTP client, cache, etc.)
• utils/ - Utility functions (logging, error handling, etc.)
• hooks/ - React hooks and utilities
• styles/ - Shared CSS and styling utilities
• testing/ - Testing utilities and helpers

Usage

Import shared components into your package:

// Import specific modules
import { logger } from '@bluefly/shared/utils';
import { HttpClient } from '@bluefly/shared/services';
import { AppError } from '@bluefly/shared/errors';

// Import all utilities
import { utils, services, constants } from '@bluefly/shared';

// Use the utilities
logger.info('Application starting');
const httpClient = new HttpClient({ baseURL: 'https://api.example.com' });

Available Components

Configuration

The shared configuration system provides a unified way to manage configuration across packages:

import { config } from '@bluefly/shared/config';

// Get configuration values
const apiUrl = config.get('api.url', 'https://default-api.bluefly.io');

// Set configuration values
config.set('api.timeout', 5000);

HTTP Client

A unified HTTP client for making API requests:

import { HttpClient } from '@bluefly/shared/services/http-client';

const apiClient = new HttpClient({
  baseURL: 'https://api.bluefly.io',
  timeout: 5000,
  retries: 3,
});

// Make requests
const data = await apiClient.get('/users');
await apiClient.post('/users', { name: 'New User' });

Error Handling

Standardized error handling:

import { 
  AppError, 
  ValidationError, 
  NotFoundError 
} from '@bluefly/shared/utils/error-utils';

// Create and throw typed errors
throw new ValidationError('Invalid input parameter');

// Convert unknown errors to AppError
try {
  // Some operation
} catch (error) {
  const appError = toAppError(error);
  logger.error(appError.message, appError.toJSON());
}

Logging

Unified logging system:

import { logger } from '@bluefly/shared/utils/logger';

logger.info('Application started');
logger.warn('Resource usage high', { memoryUsage: process.memoryUsage() });
logger.error('Failed to connect to database', { dbHost: 'localhost' });

Caching

File-based caching system:

import { cache } from '@bluefly/shared/services/cache';

// Store data with TTL in seconds
await cache.set('user:123', userData, 3600); // Cache for 1 hour

// Retrieve data
const user = await cache.get('user:123');

// Check if key exists
if (await cache.has('user:123')) {
  // Key exists and is not expired
}

Testing Utilities

Helpers for unit and integration testing:

import { 
  createMockHttpClient,
  createMockLogger,
  createTempDir
} from '@bluefly/shared/testing/test-utils';

// Create mocks
const mockHttpClient = createMockHttpClient();
mockHttpClient.mockResponse('GET', '/users', {
  status: 200,
  data: [{ id: 1, name: 'User 1' }]
});

// Use in tests
const result = await mockHttpClient.get('/users');
expect(result).toEqual([{ id: 1, name: 'User 1' }]);

Contributing

When adding new shared components, follow these guidelines:

1. Create proper TypeScript interfaces
2. Add comprehensive JSDoc comments
3. Include unit tests
4. Update this README with examples
5. Use consistent error handling and logging
6. Follow the established directory structure