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

pnpm add @schafevormfenster/streaming

TypeScript Sources (Optional)

For faster development with Vite, use TypeScript sources directly:

// 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

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

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

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

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

MIME Type Validation

Using Convenience Validators

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

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

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