Overview

The DragonFire Merlin SDK provides access to our revolutionary recursive harmonic compression technology. Merlin compression uses mathematical principles based on Phi relationships to achieve compression ratios that exceed traditional algorithms while maintaining high data fidelity.

Installation

Install the Merlin Compression SDK using npm or yarn:

npm install @dragonfire/merlin-sdk

yarn add @dragonfire/merlin-sdk

Or include it directly in your HTML:

<script src="https://cdn.dragonfire1.com/sdk/merlin-sdk-0.8.7.js"></script>

Basic Usage

Merlin offers a simple interface for basic compression and decompression operations:

ES Module Format

import { Merlin } from '@dragonfire/merlin-sdk';

// Initialize with API key for cloud service
const merlin = new Merlin({
  apiKey: 'your-api-key',  // Optional, for cloud service
  useCloud: true  // Set to false for client-side only
});

// Compress data
async function compressData(inputData) {
  try {
    const compressed = await merlin.compress(inputData);
    console.log(`Compressed size: ${compressed.byteLength} bytes`);
    console.log(`Compression ratio: ${compressed.ratio.toFixed(2)}x`);
    return compressed.data;
  } catch (error) {
    console.error('Compression error:', error);
  }
}

// Decompress data
async function decompressData(compressedData) {
  try {
    const original = await merlin.decompress(compressedData);
    return original;
  } catch (error) {
    console.error('Decompression error:', error);
  }
}

Browser Format

<script>
  // When included directly, Merlin is available as a global object
  const merlin = new DragonFire.Merlin({
    apiKey: 'your-api-key',
    useCloud: true
  });
  
  // Compress some text
  merlin.compress("Your text data here")
    .then(result => {
      console.log(`Compressed size: ${result.byteLength} bytes`);
      
      // Decompress to verify
      return merlin.decompress(result.data);
    })
    .then(originalData => {
      console.log('Decompression successful!', originalData);
    })
    .catch(error => {
      console.error('Error:', error);
    });
</script>

Advanced Features

Stream Compression

For large data sets, the streaming API offers better memory efficiency:

import { MerlinStream } from '@dragonfire/merlin-sdk';

// Create a compression stream
const compressionStream = new MerlinStream({
  mode: 'compress',
  level: 'high',
  chunkSize: 65536  // 64KB chunks
});

// Handle compressed chunks
compressionStream.on('data', (chunk) => {
  // Process or store each compressed chunk
  saveChunk(chunk);
});

compressionStream.on('end', () => {
  console.log('Compression complete');
});

// Feed data incrementally
for (const dataChunk of largeDataArray) {
  compressionStream.write(dataChunk);
}

// Signal end of input
compressionStream.end();

Parallel Processing

Leverage multi-threading for faster compression:

import { Merlin } from '@dragonfire/merlin-sdk';

const merlin = new Merlin({
  apiKey: 'your-api-key',
  useParallel: true,  // Enable parallel processing
  threads: 4          // Use 4 worker threads
});

// Parallel compression happens automatically
const compressed = await merlin.compress(largeData, {
  level: 'max'
});

Compression Options

Merlin offers various options to customize the compression process:

Example with Options

const compressed = await merlin.compress(data, {
  level: 'high',
  mode: 'text',
  harmony: 7,
  recursionDepth: 4,
  phi: true
});

API Reference

Merlin Class

Constructor

new Merlin(options)

Creates a new Merlin compression instance.

• options.apiKey (string): API key for cloud service
• options.useCloud (boolean): Whether to use cloud service
• options.useParallel (boolean): Enable parallel processing
• options.threads (number): Number of worker threads
• options.defaultLevel (string): Default compression level

Methods

compress(data, options)

Compresses the provided data.

• data (string|ArrayBuffer|TypedArray): Data to compress
• options (object): Compression options
• Returns: Promise resolving to a compression result object

decompress(data)

Decompresses previously compressed data.

• data (ArrayBuffer|TypedArray): Compressed data
• Returns: Promise resolving to original data

estimateRatio(data, options)

Estimates compression ratio without fully compressing.

• data (string|ArrayBuffer|TypedArray): Sample data
• options (object): Compression options
• Returns: Promise resolving to estimated ratio number

MerlinStream Class

Constructor

new MerlinStream(options)

Creates a streaming compression or decompression processor.

• options.mode (string): 'compress' or 'decompress'
• options.level (string): Compression level
• options.chunkSize (number): Size of processing chunks

Methods

write(chunk)

Writes a chunk of data to the stream.

• chunk (string|ArrayBuffer|TypedArray): Data chunk

end()

Signals the end of input data.

Events

• data: Emitted when a processed chunk is ready
• end: Emitted when processing is complete
• error: Emitted when an error occurs

Code Examples

Text Compression Example

import { Merlin } from '@dragonfire/merlin-sdk';

async function compressTextExample() {
  const merlin = new Merlin();
  
  const sampleText = `DragonFire's Merlin compression utilizes harmonic patterns 
  based on the golden ratio (phi) to identify repeating structures in data. 
  This approach allows for significantly higher compression ratios compared to 
  traditional algorithms, especially for text and structured data.`;
  
  try {
    // Compress with different levels
    const lowCompression = await merlin.compress(sampleText, { level: 'low' });
    const highCompression = await merlin.compress(sampleText, { level: 'high' });
    
    console.log(`Original size: ${sampleText.length} bytes`);
    console.log(`Low compression: ${lowCompression.byteLength} bytes (${lowCompression.ratio.toFixed(2)}x)`);
    console.log(`High compression: ${highCompression.byteLength} bytes (${highCompression.ratio.toFixed(2)}x)`);
    
    // Decompress to verify
    const decompressed = await merlin.decompress(highCompression.data);
    
    console.log(`Decompression successful: ${decompressed === sampleText}`);
  } catch (error) {
    console.error('Compression error:', error);
  }
}

compressTextExample();

Binary Data Example

import { Merlin } from '@dragonfire/merlin-sdk';
import { readFileSync, writeFileSync } from 'fs';

async function compressBinaryFile(inputFile, outputFile) {
  try {
    // Read binary file
    const fileData = readFileSync(inputFile);
    
    // Initialize Merlin with cloud acceleration
    const merlin = new Merlin({
      apiKey: 'your-api-key',
      useCloud: true
    });
    
    console.log(`Original size: ${fileData.byteLength} bytes`);
    
    // Compress with binary mode and max settings
    const compressed = await merlin.compress(fileData, {
      mode: 'binary',
      level: 'max',
      harmony: 10,
      recursionDepth: 6
    });
    
    console.log(`Compressed size: ${compressed.byteLength} bytes`);
    console.log(`Compression ratio: ${compressed.ratio.toFixed(2)}x`);
    
    // Save compressed file
    writeFileSync(outputFile, Buffer.from(compressed.data));
    
    return {
      originalSize: fileData.byteLength,
      compressedSize: compressed.byteLength,
      ratio: compressed.ratio
    };
  } catch (error) {
    console.error('Error compressing file:', error);
    throw error;
  }
}

compressBinaryFile('image.png', 'image.png.merlin')
  .then(result => console.log('Compression complete:', result))
  .catch(error => console.error('Failed:', error));

React Integration Example

import React, { useState } from 'react';
import { Merlin } from '@dragonfire/merlin-sdk';

const merlin = new Merlin({
  apiKey: process.env.REACT_APP_DRAGONFIRE_API_KEY
});

function FileCompressor() {
  const [file, setFile] = useState(null);
  const [compressing, setCompressing] = useState(false);
  const [result, setResult] = useState(null);
  
  const handleFileChange = (e) => {
    setFile(e.target.files[0]);
    setResult(null);
  };
  
  const compressFile = async () => {
    if (!file) return;
    
    setCompressing(true);
    setResult(null);
    
    try {
      // Read file as ArrayBuffer
      const buffer = await file.arrayBuffer();
      
      // Determine compression mode based on file type
      const mode = file.type.startsWith('text/') ? 'text' : 'binary';
      
      // Compress the file
      const start = performance.now();
      const compressed = await merlin.compress(buffer, { mode, level: 'high' });
      const duration = performance.now() - start;
      
      // Create download URL
      const blob = new Blob([compressed.data]);
      const downloadUrl = URL.createObjectURL(blob);
      
      setResult({
        originalSize: file.size,
        compressedSize: compressed.byteLength,
        ratio: compressed.ratio,
        time: duration.toFixed(2),
        downloadUrl,
        filename: `${file.name}.merlin`
      });
    } catch (error) {
      console.error('Compression error:', error);
      setResult({ error: error.message });
    } finally {
      setCompressing(false);
    }
  };
  
  return (
    

      
Merlin File Compressor
      
      

        
        
          {compressing ? 'Compressing...' : 'Compress File'}
        
      
      
      {result && !result.error && (
        

          
Compression Results
          
Original size: {(result.originalSize / 1024).toFixed(2)} KB
          
Compressed size: {(result.compressedSize / 1024).toFixed(2)} KB
          
Compression ratio: {result.ratio.toFixed(2)}x
          
Processing time: {result.time} ms
          
            Download Compressed File
          
        
      )}
      
      {result && result.error && (
        

          
Compression Error
          
{result.error}
        
      )}
    
  );
}

export default FileCompressor;