npm package: @schafevormfenster/streaming
Description: Stream processing, buffer operations, Base64 encoding, and MIME type validation
Latest version: 0.2.1

# Streaming

## Domain

Stream Processing, Buffer Operations & MIME Type Validation

## Purpose

This package provides utilities for stream processing, buffer operations with size limit enforcement, Base64 encoding, and MIME type validation.

## Installation

```bash
pnpm add @schafevormfenster/streaming
```

### TypeScript Sources (Optional)

For faster development with Vite, use TypeScript sources directly:

```typescript
// vite.config.ts - Requires tsconfig "target": "ES2022"+
export default defineConfig({
  resolve: { conditions: ['source', 'import', 'default'] }
});
```

Benefits: Faster HMR, direct debugging, better tree-shaking.

## Features

### Stream and Buffer Utilities

- **Stream-to-Buffer Conversion**: Convert streams to buffers with size limits.
- **Stream-to-Base64 Conversion**: Convert streams directly to base64 strings.
- **Buffer-to-Base64 Conversion**: Convert buffers to base64 strings.
- **Size Enforcement**: Prevent memory overflow by enforcing maximum sizes.

### MIME Type Validation

- **Generic Validation**: Flexible list-based MIME type validation.
- **Predefined Constants**: Common MIME type lists for images, documents, and streaming media.
- **Convenience Validators**: Pre-built validators for common use cases.
- **Type Safety**: TypeScript literal types for compile-time validation.

## Usage

### Stream to Buffer

```typescript
import { streamToBuffer } from "@schafevormfenster/streaming";

// Convert stream to buffer
const buffer = await streamToBuffer(stream);

// With size limit (throws if exceeded)
const buffer = await streamToBuffer(stream, 10 * 1024 * 1024); // 10MB limit
```

### Stream to Base64

```typescript
import { streamToBase64 } from "@schafevormfenster/streaming";

// Convert stream to base64
const base64String = await streamToBase64(stream);

// With size limit (throws if exceeded)
const base64String = await streamToBase64(stream, 10 * 1024 * 1024); // 10MB limit
```

### Buffer to Base64

```typescript
import { bufferToBase64 } from "@schafevormfenster/streaming";

// Convert buffer to base64
const base64String = bufferToBase64(buffer);
```

### MIME Type Validation

#### Using Convenience Validators

```typescript
import { 
  isCommonImageMimeType,
  isExtendedImageMimeType,
  isCommonDocumentMimeType,
  isExtendedDocumentMimeType,
  isStreamingMimeType
} from "@schafevormfenster/streaming";

// Validate common web-safe images (JPEG, PNG, GIF, WebP)
if (isCommonImageMimeType("image/jpeg")) {
  console.log("Valid common image format");
}

// Validate extended images (includes SVG, BMP, TIFF, AVIF, HEIC)
if (isExtendedImageMimeType("image/svg+xml")) {
  console.log("Valid extended image format");
}

// Validate documents
if (isCommonDocumentMimeType("application/pdf")) {
  console.log("Valid document format");
}

// Validate streaming media
if (isStreamingMimeType("video/mp4")) {
  console.log("Valid streaming format");
}
```

#### Using MIME Type Constants

```typescript
import { 
  COMMON_IMAGE_MIME_TYPES,
  EXTENDED_IMAGE_MIME_TYPES,
  COMMON_DOCUMENT_MIME_TYPES,
  EXTENDED_DOCUMENT_MIME_TYPES,
  STREAMING_MIME_TYPES,
  isMimeTypeInList
} from "@schafevormfenster/streaming";

// Use predefined lists directly
const isCommonImage = isMimeTypeInList(mimeType, COMMON_IMAGE_MIME_TYPES);

// Compose custom lists
const MY_ALLOWED_TYPES = [
  ...COMMON_IMAGE_MIME_TYPES,
  "application/pdf"
] as const;

const isAllowed = isMimeTypeInList(mimeType, MY_ALLOWED_TYPES);
```

#### Custom Domain-Specific Validation

```typescript
import { 
  COMMON_IMAGE_MIME_TYPES,
  COMMON_DOCUMENT_MIME_TYPES,
  isMimeTypeInList 
} from "@schafevormfenster/streaming";

// Define domain-specific allowed types for your API
export const API_ALLOWED_IMAGES = [
  "image/jpeg", 
  "image/png"
] as const; // More restrictive than common list

export const API_ALLOWED_DOCUMENTS = COMMON_DOCUMENT_MIME_TYPES; // Use as-is

// Domain-specific validators
export const isApiImageMimeType = (mimeType: string): boolean => 
  isMimeTypeInList(mimeType, API_ALLOWED_IMAGES);

export const isApiDocumentMimeType = (mimeType: string): boolean => 
  isMimeTypeInList(mimeType, API_ALLOWED_DOCUMENTS);

// All MIME types your API accepts
export const API_ALLOWED_MIME_TYPES = [
  ...API_ALLOWED_IMAGES,
  ...API_ALLOWED_DOCUMENTS
] as const;

export const isApiValidMimeType = (mimeType: string): boolean => 
  isMimeTypeInList(mimeType, API_ALLOWED_MIME_TYPES);
```

## API Reference

### Functions

#### `streamToBuffer(stream, maxSize?): Promise<Buffer>`

Converts a stream to a Buffer with optional size limit.

- **stream**: `Readable | ReadableStream | AsyncIterable<unknown>` - The stream to convert
- **maxSize**: `number` (optional) - Maximum allowed size in bytes
- **Returns**: `Promise<Buffer>` - The converted buffer
- **Throws**: Error if stream exceeds maxSize

#### `streamToBase64(stream, maxSize?): Promise<string>`

Converts a stream to a base64-encoded string with optional size limit.

- **stream**: `Readable | ReadableStream | AsyncIterable<unknown>` - The stream to convert
- **maxSize**: `number` (optional) - Maximum allowed size in bytes
- **Returns**: `Promise<string>` - The base64-encoded string
- **Throws**: Error if stream exceeds maxSize

#### `bufferToBase64(buffer): string`

Converts a Buffer to a base64-encoded string.

- **buffer**: `Buffer` - The buffer to convert
- **Returns**: `string` - The base64-encoded string

#### `isMimeTypeInList(mimeType, allowedTypes): boolean`

Generic helper to check if a MIME type exists in a list.

- **mimeType**: `string` - The MIME type to validate
- **allowedTypes**: `readonly string[]` - Array of allowed MIME types
- **Returns**: `boolean` - true if MIME type is in the list

#### `isCommonImageMimeType(mimeType): boolean`

Validates if a MIME type is a common web-safe image format (JPEG, PNG, GIF, WebP).

#### `isExtendedImageMimeType(mimeType): boolean`

Validates if a MIME type is an extended image format (includes common + SVG, BMP, TIFF, AVIF, HEIC).

#### `isCommonDocumentMimeType(mimeType): boolean`

Validates if a MIME type is a common document format (PDF).

#### `isExtendedDocumentMimeType(mimeType): boolean`

Validates if a MIME type is an extended document format (PDF, Word, Excel, plain text, CSV).

#### `isStreamingMimeType(mimeType): boolean`

Validates if a MIME type is a streaming media format (MP4, WebM, MP3, WAV, Ogg).

### Constants

#### `COMMON_IMAGE_MIME_TYPES`

Array of common web-safe image MIME types:
- `image/jpeg`
- `image/png`
- `image/gif`
- `image/webp`

#### `EXTENDED_IMAGE_MIME_TYPES`

Array of extended image MIME types (includes all common types plus):
- `image/svg+xml`
- `image/bmp`
- `image/tiff`
- `image/avif`
- `image/heic`

#### `COMMON_DOCUMENT_MIME_TYPES`

Array of common document MIME types:
- `application/pdf`

#### `EXTENDED_DOCUMENT_MIME_TYPES`

Array of extended document MIME types:
- `application/pdf`
- `application/msword`
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
- `application/vnd.ms-excel`
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
- `text/plain`
- `text/csv`

#### `STREAMING_MIME_TYPES`

Array of streaming media MIME types:
- `video/mp4`
- `video/webm`
- `audio/mpeg`
- `audio/wav`
- `audio/ogg`

### TypeScript Types

All constants have corresponding union types for compile-time validation:
- `CommonImageMimeType`
- `ExtendedImageMimeType`
- `CommonDocumentMimeType`
- `ExtendedDocumentMimeType`
- `StreamingMimeType`

## Design Principles

1. **Composability**: Generic utilities + predefined lists = flexible, reusable components
2. **Type Safety**: Use `as const` and union types for compile-time validation
3. **Separation of Concerns**: Generic logic in streaming package, domain-specific constraints in clients
4. **Pure Functions**: No side effects, predictable behavior
5. **Developer Experience**: Convenience validators for common patterns

## Responsibilities

- **Stream Processing**: Convert streams to buffers and base64 strings
- **Size Enforcement**: Prevent memory overflow by enforcing maximum sizes
- **Base64 Encoding**: Convert buffers and streams to base64
- **MIME Type Validation**: Provide flexible, reusable MIME type validation utilities
- **Type Safety**: Export TypeScript types for compile-time validation

## Boundaries

- **Usage**: Used by packages that need to process streams, validate MIME types, or encode data
- **Dependencies**: Depends on logging package for error reporting
- **Domain Logic**: Generic utilities only; domain-specific constraints belong in client packages