@smooai/file v1.1.0

About SmooAI

SmooAI is an AI-powered platform for helping businesses multiply their customer, employee, and developer experience.

Learn more on smoo.ai

About @smooai/file

A powerful file handling library for Node.js that provides a unified interface for working with files from local filesystem, S3, URLs, and more. Built with streaming in mind, it handles file bytes lazily where possible to minimize memory usage and improve performance.

Install

pnpm add @smooai/file

Key Features

🚀 Stream-First Design

• Lazy loading of file contents
• Memory-efficient processing
• Automatic stream handling
• Support for both Node.js and Web streams

📦 Multiple File Sources

• Local Filesystem

  • Read and write operations
  • File system checks
  • Metadata extraction

• URLs

  • Automatic download
  • Stream-based transfer
  • Header metadata extraction

• S3 Objects

  • Direct S3 integration (download and upload)
  • Stream-based transfer
  • Header metadata extraction
  • Signed URL generation

• FormData

  • Ease of use for Multipart FormData upload

🔍 Intelligent File Type Detection

Powered by file-type, providing:

• Magic number detection
• MIME type inference
• File extension detection
• Support for 100+ file types

📝 Rich Metadata

• File name and extension
• MIME type detection
• File size
• Last modified date
• Creation date
• File hash/checksum
• URL and path information
• Source type

Examples

• Basic Usage
• Streaming Operations
• S3 Integration
• File Type Detection
• FormData Support

Basic Usage

import File from '@smooai/file';

// Create a file from a local path
const file = await File.createFromFile('path/to/file.txt');

// Read file contents (streams automatically)
const content = await file.readFileString();
console.log(content);

// Get file metadata
console.log(file.metadata);
// {
//   name: 'file.txt',
//   mimeType: 'text/plain',
//   size: 1234,
//   extension: 'txt',
//   path: 'path/to/file.txt',
//   lastModified: Date,
//   createdAt: Date
// }

Streaming Operations

import File from '@smooai/file';

// Create a file from a URL (streams automatically)
const file = await File.createFromUrl('https://example.com/large-file.zip');

// Pipe to a destination (streams without loading entire file)
await file.pipeTo(someWritableStream);

// Read as bytes (streams in chunks)
const bytes = await file.readFileBytes();

// Save to filesystem (streams directly)
const { original, newFile } = await file.saveToFile('downloads/file.zip');

S3 Integration

import File from '@smooai/file';

// Create from S3 (streams automatically)
const file = await File.createFromS3('my-bucket', 'path/to/file.jpg');

// Upload to S3 (streams directly)
await file.uploadToS3('my-bucket', 'remote/file.jpg');

// Save to S3 (creates new file instance)
const { original, newFile } = await file.saveToS3('my-bucket', 'remote/file.jpg');

// Move to S3 (deletes local file if source was local)
const s3File = await file.moveToS3('my-bucket', 'remote/file.jpg');

// Generate signed URL
const signedUrl = await s3File.getSignedUrl(3600); // URL expires in 1 hour

File Type Detection

import File from '@smooai/file';

const file = await File.createFromFile('document.xml');

// Get file type information (detected via magic numbers)
console.log(file.mimeType); // 'application/xml'
console.log(file.extension); // 'xml'

// File type is automatically detected from:
// - Magic numbers (via file-type)
// - MIME type headers
// - File extension
// - Custom detectors

FormData Support

import File from '@smooai/file';

const file = await File.createFromFile('document.pdf');

// Convert to FormData for uploads
const formData = await file.toFormData('document');

// Use with fetch or other HTTP clients
await fetch('https://api.example.com/upload', {
    method: 'POST',
    body: formData,
});

Built With

• TypeScript
• Node.js File System API
• AWS SDK v3
• file-type for magic number-based MIME type detection
• @smooai/fetch for URL downloads
• @smooai/logger for structured logging

Contributing

Contributions are welcome! This project uses changesets to manage versions and releases.

Development Workflow

1. Fork the repository
2. Create your branch (git checkout -b amazing-feature)
3. Make your changes

4. Add a changeset to document your changes:

   pnpm changeset

   This will prompt you to:

   • Choose the type of version bump (patch, minor, or major)
   • Provide a description of the changes

5. Commit your changes (git commit -m 'Add some amazing feature')

6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Pull Request Guidelines

• Reference any related issues in your PR description

The maintainers will review your PR and may request changes before merging.

Contact

Brent Rager

• Email
• LinkedIn
• BlueSky
• TikTok
• Instagram

Smoo Github: https://github.com/SmooAI