@jesselpalmer/easy-blob

EasyBlob

Quick and easy local blob storage for Node.js applications.

Installation

npm install @jesselpalmer/easy-blob

Quick Start

JavaScript

const BlobStorage = require('@jesselpalmer/easy-blob');

// Create storage instance
const storage = new BlobStorage({
  storageDir: './uploads',    // Optional: defaults to './uploads'
  dbPath: './blobs.db'        // Optional: defaults to './blob-storage.db'
});

// Start the server
storage.start(3000);

TypeScript

import { BlobStorage, BlobStorageOptions } from '@jesselpalmer/easy-blob';

// Create storage instance with type safety
const options: BlobStorageOptions = {
  storageDir: './uploads',
  dbPath: './blobs.db'
};

const storage = new BlobStorage(options);
storage.start(3000);

API

Constructor Options

• storageDir (string): Directory to store uploaded files. Defaults to ./uploads
• dbPath (string): Path to SQLite database file. Defaults to ./blob-storage.db
• maxFileSize (number): Maximum file size in bytes. Defaults to 10485760 (10MB)
• allowedMimeTypes (string[]): Array of allowed MIME types. Empty array allows all types.

Methods

start(port)

Starts the Express server on the specified port with graceful shutdown handling.

Endpoints

POST /upload

Upload a file as multipart/form-data with field name blob.

Response: {"id": 1, "message": "File uploaded successfully"}

Errors:

• 400 - File too large, invalid file type, or no file uploaded
• 500 - Server error

GET /files

Get a list of all uploaded files with metadata.

Response: Array of file objects with id, original_name, mime_type, path, and upload_timestamp.

GET /blob/:id

Retrieve a previously uploaded file by its ID.

Response: The actual file content

Errors:

• 400 - Invalid blob ID
• 404 - Blob not found
• 500 - Server error

DELETE /blob/:id

Delete a file by its ID (removes both database record and physical file).

Response: {"message": "File deleted successfully"}

Errors:

• 400 - Invalid blob ID
• 404 - Blob not found
• 500 - Server error

Usage Examples

Basic File Upload

JavaScript:

const BlobStorage = require('@jesselpalmer/easy-blob');

const storage = new BlobStorage();
storage.start(3000);

TypeScript:

import { BlobStorage } from '@jesselpalmer/easy-blob';

const storage = new BlobStorage();
storage.start(3000);

Usage:

# Upload a file
curl -X POST -F "blob=@myfile.pdf" http://localhost:3000/upload
# Response: {"id": 1, "message": "File uploaded successfully"}

# List all files
curl http://localhost:3000/files
# Response: [{"id": 1, "original_name": "myfile.pdf", "mime_type": "application/pdf", ...}]

# Download a file
curl http://localhost:3000/blob/1 --output downloaded-file.pdf

# Delete a file
curl -X DELETE http://localhost:3000/blob/1
# Response: {"message": "File deleted successfully"}

Custom Configuration

TypeScript:

import { BlobStorage, BlobStorageOptions } from '@jesselpalmer/easy-blob';
import path from 'path';

const options: BlobStorageOptions = {
  storageDir: path.join(__dirname, 'my-uploads'),
  dbPath: path.join(__dirname, 'my-database.db'),
  maxFileSize: 5 * 1024 * 1024, // 5MB limit
  allowedMimeTypes: ['image/jpeg', 'image/png', 'application/pdf'] // Only allow specific types
};

const storage = new BlobStorage(options);
storage.start(8080);

Use Cases

• Development & Prototyping: Quick file storage without cloud setup
• Internal Tools: Simple file sharing in trusted environments
• Local Applications: Desktop/local services needing file storage
• Testing: Mock file storage for automated tests
• Small Projects: When you need basic file upload/download functionality

License

MIT

Changelog

[1.0.0] - 2025-06-16

🎉 Initial Release

First stable release of EasyBlob - Quick and easy local blob storage for Node.js applications.

✨ Features

• Simple HTTP API for file operations (upload, download, list, delete)
• SQLite database for metadata storage with automatic table initialization
• Express 5.x server with built-in middleware and routing
• TypeScript support with full type definitions
• Multer integration for multipart file uploads
• Configurable options for storage directory, database path, file size limits, and MIME type restrictions
• Graceful shutdown handling for production deployments
• Cross-platform compatibility with proper line ending handling

🔧 Configuration Options

• storageDir: Custom upload directory (default: ./uploads)
• dbPath: SQLite database file path (default: ./blob-storage.db)
• maxFileSize: File size limit in bytes (default: 10MB)
• allowedMimeTypes: Array of allowed MIME types (default: all types)

📡 API Endpoints

• POST /upload - Upload files with multipart/form-data
• GET /files - List all uploaded files with metadata
• GET /blob/:id - Download file by ID
• DELETE /blob/:id - Delete file and metadata by ID

🛡️ Security & Quality

• Zero vulnerabilities - All dependencies updated to latest secure versions
• Comprehensive test suite - 10/10 tests passing with Jest 30.x
• Code quality - Prettier formatting, Markdown linting, TypeScript strict mode
• Error handling - Proper HTTP status codes and error responses
• File validation - MIME type filtering and size limits

🏗️ Technical Stack

• Express: 5.1.0 (latest stable)
• Multer: 2.0.1 (latest with security fixes)
• SQLite3: 5.1.7
• TypeScript: 5.8.3
• Jest: 30.0.0
• Node.js: Compatible with 18.x, 20.x, 22.x, 24.x

🚀 Installation

npm install @jesselpalmer/easy-blob

📖 Documentation

• Complete TypeScript examples in README
• JSDoc comments throughout codebase
• API endpoint documentation with examples
• Configuration options with defaults

🧪 Testing

• Comprehensive test coverage for all API endpoints
• File upload/download testing
• Error handling validation
• Cross-platform CI/CD with GitHub Actions

Package Information

Package Name: @jesselpalmer/easy-blob
License: MIT
Repository: https://github.com/jesselpalmer/easy-blob
Issues: https://github.com/jesselpalmer/easy-blob/issues

Badges