filemakerrrr

THE FILEMAKERRRR

LIVE DEMO

English | Español

TL;DR

EN

Quickly create files, compress and decompress text strings directly from the browser. It uses Huffman encoding in asynchronous operations that don't block runtime, with a simple interface and support for Unicode BMP (Basic Multilingual Plane). Download from NPM and you’re ready to go, fully typed and no dependencies.

Quick Start

SUPA-F*CKING-FAST!!! (Automatically downloads the file with the compressed string)

import { Filemakerrrr } from 'filemakerrrr';
const zipper = new Filemakerrrr({}, myString);

ES

Crea archivos, comprime y descomprime rápidamente cadenas de texto desde el navegador. Emplea la codificacion Huffman en operaciones asíncronas que no bloquean el tiempo de ejecución, con una interfase sencilla y soporte de para Unicode BMP(Basic Multilingual Plane). Descarga desde NPM y listo, totalmente tipado y sin dependencias.

Inicio Rápido

SUPA-F*CKING-FAST!!! (descarga automáticamente el archivo con la cadena comprimida)

import { Filemakerrrr } from 'filemakerrrr';
const zipper = new Filemakerrrr({}, miCadena);

English

Filemakerrrr is a simple and straightforward JavaScript library for parsing files, compressing, decompressing, and downloading strings in the browser.

Features

• Fast compression and decompression of text strings and files
• Uses Huffman coding for efficient compression
• Asynchronous operations to avoid blocking execution time
• Simple interface
• Support for Unicode BMP (Basic Multilingual Plane)
• Customizable communication method

Installation

npm install filemakerrrr

Usage

import { Filemakerrrr } from 'filemakerrrr';
const zipper = new Filemakerrrr();

zipper.stringToZip(myString)
    .then(() => zipper.zip());
    .then(() => zipper.download('MyFileName'));

or handle it with async functions:

zipper.stringToZip(myString);
myFuntion = async () => {
    try {
        // ...
        await zipper.zip()
    } // ...
}

or, or, or, handle the methods that follows the zip() outside the runtime as events listeners:

// ...
zipper.stringToZip(myString);
zipper.zip();

someButton.addEventListener('pointerdown', () => {
    zipper.download('MyFileName');
});

Configuration

You can configure Filemakerrrr using an initialization object or methods during code execution:

Initialization Object

const zipper = new Filemakerrrr({
    downloadName: 'Your File name', // String
    alwaysZip: true, // Boolean
    verbose: true, // Boolean
    talkToMeCallback: myFunction, // Callback, must take a string as a parameter
    lang: 'en', // String with the international code for the language
});

Always the first parameter sould be the config object

Default configuration: FAST(But not SUPA-F*CKING-FAST)

{
    downloadName: 'myFile',
    alwaysZip: false,
    verbose: false,
    talkToMeCallback: console.log,
    lang: 'en',
}

Methods

• stringToZip(string): Takes the string to be zipped and stores it in the input memory of the class
• parseFile(file): async. Takes the file from the input field, parses it, and stores it in the input memory of the class
• zip(): async. Zips the string stored in the input memory and stores the result in the output memory of the class
• forceIt(alwaysZip): Takes a boolean; if true, forces the compression even if Filemakerrrr doesn't recommend it. If no parameter is provided, it defaults to true
• unzip(): async. Unzips the data stored in the input memory and stores the result in the output memory of the class
• download(fileName): Downloads the data stored in the output memory of the class. Takes a string as a parameter and uses it to name the file. The file extension is '.txt' if the file is not zipped or '.f4r' if it is
• talkToMe(verbose): Takes a boolean; if true, all messages are available for the callback. If no parameter is provided, it defaults to true
• addListener(callback): Takes a callback to execute every time Filemakerrrr has a message for the user. The callback must accept a string as a parameter
• flush(): Clear all stored data
• viewStats: Get compression/decompression stats
• flushStats(): Clear all stats
• input: Get the stored in memory input data
• output: Get the stored in memory output data

How It Works

Filemakerrrr uses Huffman coding to compress strings efficiently. It evaluates the input, forecasts compression rates, and decides whether to compress based on the potential savings.

zipping

flowchart TD
    A[input memory] --> B[Evaluate string]
    B --> C[Compression forecast]
    C --> D{Compression forecast rate < 1?}
    D -- Yes --> E[Zip]
    D -- No --> F[Return]

    E --> G[Create file header: 3 bytes for signature]
    G --> H[Create directory with 1 byte and fixed offset:
    - 3 bits version
    - 1 bit for compression
    - 1 bit for Huffman tree type
    - 1 bit for ASCII
    - 1 bit for extended ASCII
    - 1 bit for Unicode BMP]
    H --> I[Count characters by standard:
    - If ASCII: 7 bits for ASCII count
    - If extended ASCII: 8 bits for extended ASCII count
    - If Unicode BMP: 16 bits for Unicode count]

    I --> J[Create compression map with minHeap and build Huffman tree]
    J --> K[Arrange characters by standard]
    K --> L[Convert map to binary:
    - ASCII: 7 bits for ASCII code + 5 bits for compressed length + compressed binary code
    - Extended ASCII: 8 bits for extended ASCII code + 5 bits for compressed length + compressed binary code
    - Unicode BMP: 16 bits for Unicode code + 5 bits for compressed length + compressed binary code]

    L --> M[Zip the string using the map]
    M --> N[Add last byte with trim data]
    N --> O[Merge everything into a binary buffer]
    O --> P[output memory]

unzipping

flowchart TD
    A[input memory] --> B[Check signature]
    B --> C{Is signature valid?}
    C -- Yes --> D[Unzip]
    C -- No --> E[Return]

    D --> F[Parse directory]
    F --> G{Contains ASCII?}
    G -- Yes --> H[Set offsets for ASCII characters count]
    G -- No --> I[Add 0]
    H --> P[Get characters count by standard and set it]

    F --> J{Contains extended ASCII?}
    J -- Yes --> K[Set offsets for extended ASCII characters count]
    J -- No --> L[Add 0]
    K --> P[Get characters count by standard and set it]

    F --> M{Contains Unicode?}
    M -- Yes --> N[Set offsets for Unicode characters count]
    M -- No --> O[Add 0]
    N --> P[Get characters count by standard and set it]

    P --> Q[Go to character, get standard code, compressed length, compressed binary code]
    Q --> R[Place into unzip map, update count, repeat]
    R --> S[Get starting point of string and trim unused bits from last byte]
    S --> T[Parse and unzip the string]
    T --> U[output memory]

Zip forecast

Since not all strings compress equally, and the benefits of compression are only noticeable when there is a certain level of character repetition in sufficiently long strings, Filemakerrrr performs an approximate calculation to determine whether compression is worth it, without consuming excessive computational resources. It estimates the expected compression in the worst-case scenario, where all characters have the same frequency of repetition, creating a balanced tree with all leaves at the same level. If the forecasted compressed file is smaller than or equal to the uncompressed size, compression is performed.

Español

Filemakerrrr es una biblioteca de JavaScript simple y directa para analizar archivos, comprimir, descomprimir y descargar cadenas de texto en el navegador.

Características

• Compresión y descompresión rápida de cadenas de texto y archivos
• Utiliza codificación Huffman para una compresión eficiente
• Operaciones asíncronas para evitar bloquear el tiempo de ejecución
• Interfaz sencilla
• Soporte para Unicode BMP (Plano Multilingüe Básico)
• Método personalizable para la comunicación con el usuario

Instalación

npm install filemakerrrr

Uso estándar: FAST(But not SUPA-F*CKING-FAST)

import { Filemakerrrr } from 'filemakerrrr';
const zipper = new Filemakerrrr();

zipper.stringToZip(myString)
    .then(() => zipper.zip());
    .then(() => zipper.download('MiNombreDeArchivo'));

O úsala dentro de funciones asíncronas:

zipper.stringToZip(myString);
myFuntion = async () => {
    try {
        // ...
        await zipper.zip()
        zipper.download('MiNombreDeArchivo')
    } // ...
}

o, o, o, usa los métodos que dependen de las funciones asíncronas fuera del runtime como event listeners

// ...
zipper.stringToZip(myString);
zipper.zip();

someButton.addEventListener('pointerdown', () => {
    zipper.download('MiNombreDeArchivo');
});

Configuración

Puedes configurar Filemakerrrr usando un objeto de inicialización o métodos durante la ejecución del código:

Objeto de Inicialización

const zipper = new Filemakerrrr({
    downloadName: 'Nombre de tu archivo', // String
    alwaysZip: true, // Boolean
    verbose: true, // Boolean
    talkToMeCallback: miFuncion, // Callback, debe aceptar un string como parámetro
    lang: 'es', // String con el código internacional del idioma
});

Siempre el objeto de configuración debe ir como primer parámetro

Configuración predeterminada:

{
    downloadName: 'miArchivo',
    alwaysZip: false,
    verbose: false,
    talkToMeCallback: console.log,
    lang: 'es',
}

Métodos

• stringToZip(string): Toma la cadena a comprimir y la almacena en la memoria de entrada de la clase
• parseFile(file): async. Toma el archivo del campo de entrada, lo analiza y lo almacena en la memoria de entrada de la clase
• zip(): async. Comprime la cadena almacenada en la memoria de entrada y guarda el resultado en la memoria de salida de la clase
• forceIt(alwaysZip): Recibe un booleano; si es verdadero, fuerza la compresión incluso si Filemakerrrr no lo recomienda. Si no se proporciona un parámetro, se establece como verdadero
• unzip(): async. Descomprime los datos almacenados en la memoria de entrada y guarda el resultado en la memoria de salida de la clase
• download(fileName): Descarga los datos almacenados en la memoria de salida de la clase. Recibe una cadena como parámetro y la utiliza para nombrar el archivo. La extensión del archivo es '.txt' si no está comprimido o '.f4r' si lo está
• talkToMe(verbose): Recibe un booleano; si es verdadero, todos los mensajes están disponibles para el callback. Si no se proporciona un parámetro, se establece como verdadero
• addListener(callback): Recibe un callback para ejecutar cada vez que Filemakerrrr tiene un mensaje para el usuario. El callback debe aceptar una cadena como parámetro
• flush(): Limpia todos los datos almacenados
• viewStats: Obtiene estadísticas de compresión/descompresión
• flushStats(): Limpia todas las estadísticas
• input: Obtiene los datos de entrada almacenados en memoria
• output: Obtiene los datos de salida almacenados en memoria

Cómo Funciona

Filemakerrrr es un proyecto rápido con el que quiero facilitar la creación y compresión de archivos de texto personalizados. Utiliza la codificación Huffman para comprimir cadenas de manera eficiente. Evalúa la entrada, pronostica las tasas de compresión y decide si comprimir en función de los posibles ahorros.

zipping

flowchart TD
    A[memoria de entrada] --> B[Evaluar cadena]
    B --> C[Pronóstico de compresión]
    C --> D{Pronóstico de compresión < 1}
    D -- Sí --> E[Comprimir]
    D -- No --> F[Devolver]

    E --> G[Crear encabezado de archivo: 3 bytes para la firma]
    G --> H[Crear directorio de 1 byte con el offset fijo:
    - 3 bits para versión
    - 1 bit para compresión
    - 1 bit para tipo de árbol Huffman
    - 1 bit para ASCII
    - 1 bit para ASCII extendido
    - 1 bit para Unicode BMP]
    H --> I[Contar caracteres por estándar:
    - Si ASCII: 7 bits para cantidad de caracteres ASCII
    - Si ASCII extendido: 8 bits para cantidad de caracteres ASCII extendidos
    - Si Unicode BMP: 16 bits para cantidad de caracteres Unicode]

    I --> J[Crear mapa de compresión con minHeap y construir el árbol Huffman]
    J --> K[Ordenar los caracteres por estándar]
    K --> L[Convertir el mapa a binario:
    - ASCII: 7 bits para el código ASCII + 5 bits para longitud comprimida + código binario comprimido
    - ASCII extendido: 8 bits para el código ASCII extendido + 5 bits para longitud comprimida + código binario comprimido
    - Unicode BMP: 16 bits para el código Unicode + 5 bits para longitud comprimida + código binario comprimido]

    L --> M[Comprimir la cadena usando el mapa]
    M --> N[Agregar el último byte con los datos de recorte]
    N --> O[Fusionar todo en un buffer binario]
    O --> P[memoria de salida]

unzipping

flowchart TD
    A[memoria de entrada] --> B[Verificar firma]
    B --> C{¿Firma válida?}
    C -- Sí --> D[Descomprimir]
    C -- No --> E[Retornar]

    D --> F[Analizar directorio]
    F --> G{¿Contiene ASCII?}
    G -- Sí --> H[Establecer offsets para el conteo de caracteres ASCII]
    G -- No --> I[Añadir 0]
    H --> P[Obtener el conteo de caracteres por estándar y configurarlo]

    F --> J{¿Contiene ASCII extendido?}
    J -- Sí --> K[Establecer offsets para el conteo de caracteres ASCII extendido]
    J -- No --> L[Añadir 0]
    K --> P[Obtener el conteo de caracteres por estándar y configurarlo]

    F --> M{¿Contiene Unicode?}
    M -- Sí --> N[Establecer offsets para el conteo de caracteres Unicode]
    M -- No --> O[Añadir 0]
    N --> P[Obtener el conteo de caracteres por estándar y configurarlo]

    P --> Q[Ir al carácter, obtener el código estándar, longitud comprimida, código binario comprimido]
    Q --> R[Colocar en el mapa de descompresión, actualizar conteo, repetir]
    R --> S[Obtener el punto de inicio de la cadena y recortar los bits no utilizados del último byte]
    S --> T[Analizar y descomprimir la cadena]
    T --> U[memoria de salida]

Pronóstico de compresión

Dado que no todas las cadenas se comprimen de la misma manera y los beneficios de la compresión solo se notan cuando hay cierto nivel de repetición en cadenas lo suficientemente largas, Filemakerrrr realiza un cálculo aproximado para determinar si es conveniente comprimir o no, evitando así un alto consumo de recursos computacionales. Para ello, estima la compresión esperada en el peor escenario posible: cuando todos los caracteres se repiten con la misma frecuencia, creando un árbol balanceado donde todas las hojas están al mismo nivel. Si el pronóstico de tamaño del archivo comprimido resulta ser igual o más pequeño que el original, se procede con la compresión.