@thalorlabs/middleware/PUBLISHING.md

Express.js middleware collection for TypeScript applications with authentication, logging, and error handling

# Publishing Guide

This guide is for developers who want to publish updates to the `@thalorlabs/middleware` package.

## Prerequisites

1. Ensure you have an npm account and are logged in:

   ```bash
   npm login
   ```

2. Make sure you have the necessary permissions to publish to the `@thalorlabs` scope.

## Build and Validation

Before publishing, ensure the package builds, tests pass, and TypeScript compiles without errors:

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Check test coverage
npm run test:coverage
```

## Publishing

1. **Version the package** (choose one):

   ```bash
   # Patch version (1.0.0 -> 1.0.1)
   npm version patch

   # Minor version (1.0.0 -> 1.1.0)
   npm version minor

   # Major version (1.0.0 -> 2.0.0)
   npm version major
   ```

   **Semantic Versioning Guide:**

   - **PATCH**: Bug fixes that don't add features or break existing functionality
     - Examples: Fixing middleware implementations, documentation updates, minor middleware property adjustments
   - **MINOR**: Adding new features that are backward compatible
     - Examples: New middleware components, new configuration options, optional middleware properties, new exports
   - **MAJOR**: Breaking changes that could break existing code
     - Examples: Removing middleware components, changing required middleware parameters, changing middleware behavior, breaking middleware signature changes

2. **Publish to npm**:

   ```bash
   npm publish
   ```

   **Note**: The `prepublishOnly` script automatically runs:

   - `npm run build` - Builds the package and generates type definitions

   Publishing will fail if the build fails or TypeScript compilation errors exist.

## Package Structure

The package is configured as an ES module with the following structure:

- **Main entry**: `./dist/index.js`
- **Types**: `./dist/index.d.ts`
- **Individual exports**: Available at `@thalorlabs/middleware/protect`, `@thalorlabs/middleware/TryCatchMiddleware`, etc.

## Development

### Scripts

- `npm run build` - Build the package and generate type definitions
- `npm run clean` - Clean build artifacts
- `npm test` - Run the test suite
- `npm run test:coverage` - Run tests with coverage reporting

### Configuration

- **TypeScript**: Configured in `tsconfig.json`
- **Build output**: `dist/` directory
- **Package files**: Defined in `.npmignore`

### Middleware Safety

This package focuses on providing comprehensive middleware components:

- **Express compatibility**: All middleware follows Express.js patterns
- **TypeScript definitions**: Compile-time type checking for middleware parameters
- **Error handling**: Comprehensive error handling and response formatting
- **Configuration options**: Flexible configuration for different use cases
- **Test coverage**: Comprehensive test suite with high coverage

### Third-Party Middleware Policy

**This package only contains ThalorLabs middleware components** - never publish third-party library middleware.

- ✅ Publish: `protect`, `TryCatchMiddleware`, `protectedAccessMiddleware` (our middleware contracts)
- ❌ Never publish: Express.js built-in middleware, third-party authentication middleware, external logging middleware
- Keep third-party middleware local to the service that uses the library
- This ensures stable middleware contracts and prevents third-party library changes from breaking our ecosystem

## Breaking Changes

When making breaking changes to middleware components:

1. **Document the change** in the changelog
2. **Update major version** using `npm version major`
3. **Consider migration guide** for complex changes
4. **Test with dependent packages** before publishing
5. **Ensure backward compatibility** where possible

## Dependencies

This package depends on:

- `@thalorlabs/errors` - Error handling classes for consistent error responses
- `@thalorlabs/types` - Type definitions and HTTP status codes
- `express` - Express.js framework (peer dependency)
- `uuid` - UUID generation for request tracking
- `zod` - Schema validation (for error handling)

Ensure these dependencies are compatible with your target environment.

## Middleware Integration

### Express.js Integration

The middleware components are designed to work seamlessly with Express.js:

```typescript
import express from 'express';
import {
  protect,
  TryCatchMiddleware,
  protectedAccessMiddleware,
} from '@thalorlabs/middleware';

const app = express();

// Basic authentication
app.use('/api', TryCatchMiddleware(protect));

// Protected routes
app.get(
  '/api/data',
  protectedAccessMiddleware(async (req, res) => {
    res.json({ data: 'protected data' });
  }, 'api-key')
);
```

### Error Handling Integration

The middleware integrates with `@thalorlabs/errors` for consistent error responses:

```typescript
import { TryCatchMiddleware } from '@thalorlabs/middleware';
import { ValidationError } from '@thalorlabs/errors';

app.get(
  '/api/example',
  TryCatchMiddleware(async (req, res) => {
    if (!req.query.id) {
      throw new ValidationError('ID parameter is required');
    }

    res.json({ success: true });
  })
);
```

## Testing

Before publishing, ensure all tests pass:

```bash
# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

## Quality Assurance

### Pre-publish Checklist

- [ ] All tests pass (`npm test`)
- [ ] TypeScript compiles without errors (`npm run build`)
- [ ] Test coverage meets requirements (`npm run test:coverage`)
- [ ] Documentation is up to date
- [ ] README.md includes new middleware components
- [ ] Version number is appropriate for changes
- [ ] No breaking changes without major version bump
- [ ] Dependencies are up to date and compatible

### Code Quality

- [ ] All middleware functions have JSDoc documentation
- [ ] Examples are provided for all middleware components
- [ ] TypeScript types are properly defined
- [ ] Error handling is comprehensive
- [ ] Configuration options are well documented

## Troubleshooting

### Common Publishing Issues

**Build Failures**

- Check TypeScript compilation errors
- Verify all imports are correct
- Ensure all dependencies are installed

**Test Failures**

- Run tests locally before publishing
- Check test coverage requirements
- Verify all middleware components are tested

**Permission Issues**

- Ensure you're logged into npm (`npm login`)
- Verify you have publish permissions for `@thalorlabs` scope
- Check package.json name and scope

**Version Conflicts**

- Check if version already exists on npm
- Use `npm view @thalorlabs/middleware versions` to see published versions
- Increment version appropriately

## Resources

- [DEVELOPMENT.md](./DEVELOPMENT.md) - Development guide for adding middleware components
- [DOCSTYLE.md](./DOCSTYLE.md) - Documentation standards
- [README.md](./README.md) - User documentation