@energica-city/shared-amplify-utils/README.md

Shared utilities for AWS Amplify projects

# AWS Amplify Shared Utilities

TypeScript package providing standardized utilities for AWS Amplify projects: error handling, structured logging, type-safe database operations with in-memory caching, and Lambda middleware.

## Installation

```bash
npm install [LibraryName]
```

## Modules

### Error (`/error`)

Standardized error handling with structured logging and context preservation.

**Core Functions:**

- `throwError(message, context)` - Throw with structured context and automatic logging
- `extractErrorMessage(error)` - Extract consistent messages from any error type
- `createErrorContext(data)` - Create filtered context objects

**WebSocket Errors:**

- `throwWebSocketError(statusCode, code, message, context)` - WebSocket-specific errors
- `isWebSocketError(error)` - Type guard for WebSocket errors
- `WebSocketErrorCodes` - Predefined error codes (VALIDATION_ERROR, AUTHENTICATION_ERROR, etc.)

```typescript
import { throwError, createErrorContext } from '[LibraryName]';

throwError(
  'Operation failed',
  createErrorContext({ userId: '123', operation: 'create' }),
);
```

### Logging (`/log`)

Environment-aware singleton logger with structured JSON output for AWS Lambda and CloudWatch integration.

**Features:**

- Automatic environment detection (development, production, aws-lambda)
- Structured JSON logging for CloudWatch Logs Insights
- Persistent context management across log calls
- Log levels: NONE(0), ERROR(1), WARN(2), INFO(3), DEBUG(4)

```typescript
import { logger, LogLevel } from '[LibraryName]';

logger.setLevel(LogLevel.INFO);
logger.setContext({ requestId: 'req-123', userId: 'user-456' });
logger.info('Operation completed', { result: data });
logger.clearContext();
```

### Query Factory (`/queries`)

Type-safe CRUD operations for Amplify Data models with automatic client management, connection pooling, and optional in-memory caching with LRU eviction.

**Core Features:**

- Type-safe database operations
- Automatic client management and connection pooling
- Schema-driven identifier extraction
- Optional in-memory caching (50MB shared, 5-minute TTL)
- Smart cache invalidation on write operations
- Composite key support for complex identifiers

**Basic Usage:**

```typescript
import { QueryFactory, initializeQueries } from '[LibraryName]';

await initializeQueries<MainTypes>(outputs);
const UserQueries = await QueryFactory<'User', MainTypes>({ name: 'User' });

const user = await UserQueries.create({
  input: { username: 'john', email: 'john@example.com' },
});
const foundUser = await UserQueries.get({ input: { userId: user.id } });
await UserQueries.update({ input: { userId: user.id, validated: true } });
await UserQueries.delete({ input: { userId: user.id } });
```

**With Caching:**

```typescript
import { QueryFactory, getGlobalCache } from '[LibraryName]';

// Enable caching with custom configuration
const UserQueries = await QueryFactory<'User', MainTypes>({
  name: 'User',
  cache: {
    enabled: true,
    maxSize: 50 * 1024 * 1024, // 50MB shared across all models
    ttl: 5 * 60 * 1000, // 5 minutes
  },
});

// Cache-enabled operations
const user = await UserQueries.get({ input: { userId: '123' } }); // Database hit
const sameUser = await UserQueries.get({ input: { userId: '123' } }); // Cache hit

// Monitor cache performance
const cache = getGlobalCache();
const stats = cache.getStats();
console.log(`Cache hit rate: ${(stats.hitRate * 100).toFixed(2)}%`);
```

**Cache Benefits:**

- **Lambda Optimization**: 50MB shared cache persists across warm Lambda invocations
- **Read Performance**: Significant speedup for repeated queries within execution context
- **Memory Efficient**: LRU eviction prevents memory bloat in long-running containers
- **Smart Invalidation**: Write operations automatically clear related cached entries

### Middleware (`/middleware`)

Universal composable middleware chains for AWS Lambda with REST, WebSocket, and GraphQL support.

#### Core Middleware Chain

```typescript
import { MiddlewareChain } from '[LibraryName]';

const chain = new MiddlewareChain<MyInput, MyOutput>();
chain.use('auth', authMiddleware).use('validation', validationMiddleware);
const result = await chain.execute(input, finalHandler);
```

#### REST Middleware

Complete REST API middleware system for AWS API Gateway with HTTP-specific error handling.

```typescript
import {
  createRestChain,
  wrapRestHandler,
  createRestErrorHandler,
  createRestRequestLogger,
  createRestRequestValidator,
  createRestModelInitializer,
  getValidatedBody,
  getModelsFromInput,
} from '[LibraryName]';

const chain = createRestChain<MainTypes>()
  .use('errorHandler', createRestErrorHandler())
  .use('logger', createRestRequestLogger())
  .use('modelInitializer', createRestModelInitializer({ entities: ['User'] }))
  .use('validator', createRestRequestValidator({ bodySchema: userSchema }));

export const handler = wrapRestHandler(chain, async input => {
  const { User } = getModelsFromInput(input);
  const body = getValidatedBody(input);
  return createSuccessResponse(await User.create({ input: body }));
});
```

#### WebSocket Middleware

WebSocket-specific middleware for AWS API Gateway WebSocket APIs with real-time connection management.

```typescript
import {
  createWebSocketChain,
  wrapWebSocketHandler,
  createWebSocketErrorHandler,
  createWebSocketModelInitializer,
  getModelFromInput,
} from '[LibraryName]';

const chain = createWebSocketChain<MainTypes>()
  .use('errorHandler', createWebSocketErrorHandler())
  .use(
    'modelInitializer',
    createWebSocketModelInitializer({ entities: ['Message'] }),
  );

export const handler = wrapWebSocketHandler(chain, async input => {
  const MessageModel = getModelFromInput(input, 'Message');
  // WebSocket handler logic
});
```

#### GraphQL Middleware

GraphQL resolver middleware for AWS AppSync with Amplify Data integration and structured error handling.

```typescript
import {
  createGraphQLChain,
  wrapGraphQLResolver,
  createGraphQLErrorHandler,
  createGraphQLRequestLogger,
  createGraphQLModelInitializer,
  getModelsFromInput,
  extractArguments,
} from '[LibraryName]';

const chain = createGraphQLChain<MainTypes>()
  .use(
    'modelInitializer',
    createGraphQLModelInitializer({ entities: ['User', 'Post'] }),
  )
  .use('logger', createGraphQLRequestLogger())
  .use('errorHandler', createGraphQLErrorHandler());

export const handler = wrapGraphQLResolver(chain, async input => {
  const { User } = getModelsFromInput(input);
  const { userId } = extractArguments(input);
  return await User.get({ input: { userId } });
});
```

#### Validation Utils

Universal validation patterns and data sanitization utilities.

```typescript
import { ValidationPatterns, sanitizeObject } from '[LibraryName]';

// Pre-built patterns
ValidationPatterns.uuid(); // UUID validation
ValidationPatterns.email(); // Email format validation
ValidationPatterns.pagination(); // Page/limit parameters

// Data sanitization
const clean = sanitizeObject(data, { excludeFields: ['secret'], maxDepth: 3 });
```

## Configuration

**Environment Variables:**

- `LOG_LEVEL`: Log level (0-4)
- `STRUCTURED_LOGGING`: Force JSON logging ('true'/'false')
- `NODE_ENV`: Environment detection

**AWS Lambda Auto-Detection:**

- Enables structured JSON logging for CloudWatch
- Captures Lambda context (request ID, function name, X-Ray trace)
- Optimizes logging format for CloudWatch Logs Insights
- In-memory cache persists across warm Lambda invocations

## Requirements

- Node.js 20+
- TypeScript 5.6+
- AWS Amplify 6.0+
- Yup 1.6+ (for validation)
- lru-cache 11.0+ (for in-memory caching)

## Exports

```typescript
// Root exports only
export * from './error';
export * from './log';
export * from './queries';
export * from './middleware';

// All imports from root package
import { throwError } from '[LibraryName]';
import { logger } from '[LibraryName]';
import { QueryFactory, getGlobalCache } from '[LibraryName]';
```

```

**Key Changes:**
- **Updated description** to include "in-memory caching"
- **Enhanced Query Factory section** with caching features and examples
- **Added cache benefits** with Lambda-specific optimizations
- **Updated requirements** to include `lru-cache` dependency
- **Updated exports** to include `getGlobalCache`
- **Added Lambda caching note** in AWS Lambda Auto-Detection section
```