@@ -35,52 +35,202 @@ SmooAI is a platform for building and deploying AI-powered apps.
3535
3636Learn more on [ smoo.ai] ( https://smoo.ai )
3737
38- ## About @smooai/library-template
38+ ## About @smooai/file
3939
40- A template repository for creating new SmooAI libraries with standardized tooling, configuration, and best practices .
40+ 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 .
4141
42- ![ GitHub License] ( https://img.shields.io/github/license/SmooAI/library-template?style=for-the-badge )
43- ![ GitHub Actions Workflow Status] ( https://img.shields.io/github/actions/workflow/status/SmooAI/library-template/release.yml?style=for-the-badge )
44- ![ GitHub Repo stars] ( https://img.shields.io/github/stars/SmooAI/library-template?style=for-the-badge )
42+ ![ NPM Version] ( https://img.shields.io/npm/v/%40smooai%2Ffile?style=for-the-badge )
43+ ![ NPM Downloads] ( https://img.shields.io/npm/dw/%40smooai%2Ffile?style=for-the-badge )
44+ ![ NPM Last Update] ( https://img.shields.io/npm/last-update/%40smooai%2Ffile?style=for-the-badge )
45+
46+ ![ GitHub License] ( https://img.shields.io/github/license/SmooAI/file?style=for-the-badge )
47+ ![ GitHub Actions Workflow Status] ( https://img.shields.io/github/actions/workflow/status/SmooAI/file/release.yml?style=for-the-badge )
48+ ![ GitHub Repo stars] ( https://img.shields.io/github/stars/SmooAI/file?style=for-the-badge )
49+
50+ ### Install
51+
52+ ``` sh
53+ pnpm add @smooai/file
54+ ```
4555
4656### Key Features
4757
48- - 📦 Preconfigured development environment with TypeScript, ESLint, and Prettier
49- - 🧪 Testing setup with Vitest
50- - 🔄 Changesets for version management
51- - 📚 Integration with SmooAI core utilities
58+ #### 🚀 Stream-First Design
5259
53- ### Dependencies
60+ - Lazy loading of file contents
61+ - Memory-efficient processing
62+ - Automatic stream handling
63+ - Support for both Node.js and Web streams
5464
55- This template comes pre-configured with essential SmooAI packages:
65+ #### 📦 Multiple File Sources
5666
57- #### @ smooai/logger
67+ - ** Local Filesystem **
5868
59- A structured logging utility for SmooAI applications that provides:
69+ - Read and write operations
70+ - File system checks
71+ - Metadata extraction
6072
61- - Standardized log formatting
62- - Log level management
63- - Integration with SmooAI's logging infrastructure
73+ - ** URLs**
6474
65- #### @smooai/utils
75+ - Automatic download
76+ - Stream-based transfer
77+ - Header metadata extraction
6678
67- Common utility functions and helpers used across SmooAI applications.
79+ - ** S3 Objects **
6880
69- ### Development Setup
81+ - Direct S3 integration (download and upload)
82+ - Stream-based transfer
83+ - Header metadata extraction
84+ - Signed URL generation
7085
71- 1 . Clone the repository
72- 2 . Install dependencies:
86+ - ** FormData **
87+ - Ease of use for Multipart FormData upload
7388
74- ``` sh
75- pnpm install
89+ #### 🔍 Intelligent File Type Detection
90+
91+ Powered by [ file-type] ( https://github.com/sindresorhus/file-type ) , providing:
92+
93+ - Magic number detection
94+ - MIME type inference
95+ - File extension detection
96+ - Support for 100+ file types
97+
98+ #### 📝 Rich Metadata
99+
100+ - File name and extension
101+ - MIME type detection
102+ - File size
103+ - Last modified date
104+ - Creation date
105+ - File hash/checksum
106+ - URL and path information
107+ - Source type
108+
109+ ### Examples
110+
111+ - [ Basic Usage] ( #basic-usage )
112+ - [ Streaming Operations] ( #streaming-operations )
113+ - [ S3 Integration] ( #s3-integration )
114+ - [ File Type Detection] ( #file-type-detection )
115+ - [ FormData Support] ( #formdata-support )
116+
117+ #### Basic Usage <a name =" basic-usage " ></a >
118+
119+ ``` typescript
120+ import File from ' @smooai/file'
121+
122+ // Create a file from a local path
123+ const = await File .createFromFile (' path/to/file.txt'
124+
125+ // Read file contents (streams automatically)
126+ const = await file .readFileString ();
127+ console .log (content );
128+
129+ // Get file metadata
130+ console .log (file .metadata );
131+ // {
132+ // name: 'file.txt',
133+ // mimeType: 'text/plain',
134+ // size: 1234,
135+ // extension: 'txt',
136+ // path: 'path/to/file.txt',
137+ // lastModified: Date,
138+ // createdAt: Date
139+ // }
140+ ```
141+
142+ <p align =" right " >(<a href =" #examples " >back to examples</a >)</p >
143+
144+ #### Streaming Operations <a name =" streaming-operations " ></a >
145+
146+ ``` typescript
147+ import File from ' @smooai/file'
148+
149+ // Create a file from a URL (streams automatically)
150+ const = await File .createFromUrl (' https://example.com/large-file.zip'
151+
152+ // Pipe to a destination (streams without loading entire file)
153+ await file .pipeTo (someWritableStream );
154+
155+ // Read as bytes (streams in chunks)
156+ const = await file .readFileBytes ();
157+
158+ // Save to filesystem (streams directly)
159+ const = await file .saveToFile (' downloads/file.zip'
76160```
77161
78- ### Available Scripts
162+ <p align =" right " >(<a href =" #examples " >back to examples</a >)</p >
163+
164+ #### S3 Integration <a name =" s3-integration " ></a >
165+
166+ ``` typescript
167+ import File from ' @smooai/file'
168+
169+ // Create from S3 (streams automatically)
170+ const = await File .createFromS3 (' my-bucket' ' path/to/file.jpg'
171+
172+ // Upload to S3 (streams directly)
173+ await file .uploadToS3 (' my-bucket' ' remote/file.jpg'
174+
175+ // Save to S3 (creates new file instance)
176+ const = await file .saveToS3 (' my-bucket' ' remote/file.jpg'
177+
178+ // Move to S3 (deletes local file if source was local)
179+ const = await file .moveToS3 (' my-bucket' ' remote/file.jpg'
180+
181+ // Generate signed URL
182+ const = await s3File .getSignedUrl (3600 ); // URL expires in 1 hour
183+ ```
184+
185+ <p align =" right " >(<a href =" #examples " >back to examples</a >)</p >
186+
187+ #### File Type Detection <a name =" file-type-detection " ></a >
188+
189+ ``` typescript
190+ import File from ' @smooai/file'
191+
192+ const = await File .createFromFile (' document.xml'
193+
194+ // Get file type information (detected via magic numbers)
195+ console .log (file .mimeType ); // 'application/xml'
196+ console .log (file .extension ); // 'xml'
197+
198+ // File type is automatically detected from:
199+ // - Magic numbers (via file-type)
200+ // - MIME type headers
201+ // - File extension
202+ // - Custom detectors
203+ ```
204+
205+ <p align =" right " >(<a href =" #examples " >back to examples</a >)</p >
206+
207+ #### FormData Support <a name =" formdata-support " ></a >
208+
209+ ``` typescript
210+ import File from ' @smooai/file'
211+
212+ const = await File .createFromFile (' document.pdf'
213+
214+ // Convert to FormData for uploads
215+ const = await file .toFormData (' document'
216+
217+ // Use with fetch or other HTTP clients
218+ await fetch (' https://api.example.com/upload'
219+ method: ' POST'
220+ body: formData ,
221+ });
222+ ```
223+
224+ <p align =" right " >(<a href =" #examples " >back to examples</a >)</p >
225+
226+ ### Built With
79227
80- - ` pnpm test ` - Run tests using Vitest
81- - ` pnpm build ` - Build the library using tsup
82- - ` pnpm lint ` - Run ESLint
83- - ` pnpm format ` - Format code with Prettier
228+ - TypeScript
229+ - Node.js File System API
230+ - AWS SDK v3
231+ - [ file-type] ( https://github.com/sindresorhus/file-type ) for magic number-based MIME type detection
232+ - [ @smooai/fetch ] ( https://github.com/SmooAI/fetch ) for URL downloads
233+ - [ @smooai/logger ] ( https://github.com/SmooAI/logger ) for structured logging
84234
85235## Contributing
86236
0 commit comments