diff --git a/README.md b/README.md index b93bab1..84281f0 100644 --- a/README.md +++ b/README.md @@ -5,35 +5,55 @@ [![npm](https://img.shields.io/npm/v/@studioframes/condense?colorA=006AFF&colorB=000000)](https://www.npmjs.com/package/@studioframes/condense) [![downloads](https://img.shields.io/npm/dt/@studioframes/condense?labelColor=006AFF&color=000000)](https://www.npmjs.com/package/@studioframes/condense) -**A high-performance, completely stateless file optimization and minification engine for Node.js. Condense handles images, video, audio, and code natively in-memory (RAM) using Buffers and Streams, completely bypassing the local server disk.** - -

- Features • - Installation • - Usage -

+**Condense is a high-performance, stateless file optimization and minification engine for [Node.js](https://nodejs.org). It optimizes images, audio, video, and code entirely in-memory using Buffers and Streams, and avoids writing temporary files to disk.** -## Features -- **Zero Disk I/O:** Fully streaming and buffer-based architecture to minimize memory overhead. -- **Granular Bypass Rules:** Add `data-condense-ignore` to any HTML tag (or `/* condense-ignore */` in JS/CSS) to prevent minification on a per-element or per-file basis. -- **Multi-Format Pipeline:** - - Code & Markup: JS, CSS, JSON, HTML - - Media: MP4, MP3, WAV - - Images: JPG, PNG, WebP +## Introduction + +Condense provides fast, in-memory optimization for media and code. It exists to offer low-latency, stateless processing for server-side and serverless environments where temporary disk I/O is undesirable or unavailable. Unlike traditional tools that rely on intermediate temporary files, Condense processes uploads and assets using Buffers and Streams, returning optimized Buffers or Streams ready to send in responses. + +### Table of Contents +- Why Condense? +- Features +- Supported Formats +- Installation +- Quick Start +- Usage +- Ignore Directives +- API Reference +- Architecture Diagram +- Benchmarks +- System Requirements +- License + +## Why Condense? + +- **No temporary files:** Processes files entirely in-memory using Buffers and Streams without writing temporary files to disk. +- **Stateless architecture:** Optimizations are performed per-request without persistent state, easing horizontal scaling. +- **API-friendly:** Designed to integrate cleanly into HTTP APIs and microservices. +- **Serverless-ready:** Works well in ephemeral environments (Cloud Functions, Lambda-like runtimes) where disk access is limited. +- **High-throughput:** Efficient pipelines suitable for high-volume media processing. +- **Low-latency:** Optimized for minimal added latency in request/response flows. -## System Requirements +## Features +- In-memory Buffer & Stream processing (no temporary disk writes) +- Image, audio, video, and code/markup optimization +- Express middleware and standalone CLI options +- Ignore directives to opt-out specific regions or files from minification -Condense utilizes modern native binary distributions (`sharp`, `ffmpeg-static`) which compile against updated Node-API architectures. +## Supported Formats -* **Minimum Node.js Version:** `20.9.0` (or higher) -* **Recommended Environments:** Node **20 LTS** or Node **22 LTS** -* **Forward Compatibility:** Fully supports newer major engine releases (e.g., Node 23, Node 24+). +| Category | Formats | +| --- | --- | +| Images | PNG, JPG, JPEG, WebP | +| Audio | MP3, WAV | +| Video | MP4 | +| Code & Markup | HTML, CSS, JavaScript, JSON | ## Installation -Using a package manager: +Install with your preferred package manager: #### npm @@ -59,21 +79,33 @@ pnpm add @studioframes/condense bun add @studioframes/condense ``` -## Usage +## Quick Start -### Option A: Standalone CLI Server -Run a dedicated Condense microservice directly from your terminal: +The simplest in-process example — optimize an image Buffer and get back an optimized Buffer: -```bash -npx @studioframes/condense -``` -*Defaults to port `3000`. You can configure the port using the `PORT` environment variable:* -```bash -PORT=8080 npx @studioframes/condense +```javascript +const { optimizeImage } = require('@studioframes/condense'); + +async function simpleOptimize(rawBuffer) { + const { buffer: optimized, outMime } = await optimizeImage(rawBuffer, 'image/png', 'quality'); + // send `optimized` as the HTTP response body with Content-Type `outMime` + return { optimized, outMime }; +} + +// Usage: pass a Buffer (e.g., from file upload or fetch response) ``` -### Option B: Express Middleware / Sub-App -Mount Condense directly onto an existing Express application router: +## Usage + +Condense can run as a standalone CLI server, be mounted as Express middleware, or be used programmatically. + +- CLI: `npx @studioframes/condense` (defaults to port 3000; set `PORT` to override) +- Express: mount `condenseApp` on a route to accept uploads +- Programmatic: use helpers such as `optimizeImage`, `optimizeText`, `optimizeMediaStream` + +### Examples + +### A. Express Middleware ```javascript const express = require('express'); @@ -89,8 +121,7 @@ app.listen(8080, () => { }); ``` -### Option C: Programmatic Helper SDK -Import the low-level processing functions to optimize Buffers directly inside your codebase without HTTP routing: +### B. Programmatic Helper SDK ```javascript const { optimizeImage, optimizeText, optimizeMediaStream } = require('@studioframes/condense'); @@ -105,28 +136,24 @@ const { buffer: textBuffer, outMime: textMime } = await optimizeText(rawHtmlBuff const { stream, outMime: mediaMime } = optimizeMediaStream(rawVideoBuffer, 'video/mp4', 'quality'); ``` +## Ignore Directives +Use ignore directives to prevent minification for a file or a specific region. -## Granular Ignorance (Opt-Outs) +- HTML: add `data-condense-ignore` to any element (or `` to ignore the whole document). +- JS/CSS: add the comment `/* condense-ignore */` anywhere in the file to bypass minification. -Condense supports local directives so that specific code segments are not modified during minification. - -### In HTML Documents -Add the `data-condense-ignore` attribute to any tag (or the root `` tag to ignore the whole file). Condense protects that tag and all its nested children: +Example (HTML): ```html - -
-

Some formatted text here.

- +
+ 
+    Preserved spacing and content here
+
- - -

This paragraph gets minified.

``` -### In CSS & JavaScript -Add the `/* condense-ignore */` comment anywhere inside your JS or CSS file to bypass minification entirely: +Example (JS): ```javascript /* condense-ignore */ @@ -136,16 +163,23 @@ function legacyCode() { } ``` -## API Endpoint Reference (For Options A & B) +Example (CSS): -### `POST /optimize` -Optimizes an uploaded file in-memory. +```css +/* condense-ignore */ +p { + color: red; + text-align: center; +} +``` -**Payload (Multipart Form-Data):** -- `file`: The binary file (Max 50MB) -- `method`: `quality` (visually lossless, default) or `extreme` (aggressive size reduction) +## API Reference (selected) -**Example Request:** +POST `/optimize` +- Multipart form: `file` (binary), `method` (`quality` | `extreme`) +- Returns optimized binary in the response body with appropriate `Content-Type`. + +### Example Request: ```bash curl -X POST http://localhost:3000/v1/optimize \ -F "file=@./photo.png" \ @@ -153,6 +187,37 @@ curl -X POST http://localhost:3000/v1/optimize \ --output photo-condensed.webp ``` +## Architecture Diagram + +``` +Client Upload +↓ +Buffer +↓ +Condense +↓ +Buffer/Stream +↓ +Response +``` + +Short explanation: uploads are received into memory (Buffers or Streams), processed by Condense in-memory, and returned as an optimized Buffer or Stream without intermediate disk writes. + +## Benchmarks* + +| File Type | Original Size | Optimized Size | +| --- | ---: | ---: | +| PNG | 4.2 MB | 1.1 MB | +| MP4 | 25 MB | 9 MB | +| HTML | 120 KB | 42 KB | + +*These numbers are illustrative. Actual savings vary depending on content, encoding, and chosen optimization method. + +## System Requirements + +- Minimum Node.js: >= 20.9 +- Uses native binaries (`sharp`, `ffmpeg-static`) where applicable + ## License -This Project is managed by **Studio Frames** and is licensed under the terms of the **Apache License 2.0**. See [LICENSE](https://github.com/studioframes/Condense/edit/main/LICENSE) to learn more. +This project is managed by Studio Frames and is licensed under the Apache License 2.0. See [https://github.com/studioframes/Condense/blob/main/LICENSE](https://github.com/studioframes/Condense/blob/main/LICENSE) for the full text.