Package Exports

@droply/sdk
@droply/sdk/package.json
@droply/sdk/platforms
@droply/sdk/platforms/bundler
@droply/sdk/platforms/nodejs
@droply/sdk/platforms/web
@droply/sdk/services
@droply/sdk/services/registry
@droply/sdk/types
@droply/sdk/types/config
@droply/sdk/types/core
@droply/sdk/types/errors
@droply/sdk/types/events
@droply/sdk/types/index
@droply/sdk/types/platform
@droply/sdk/types/registry
@droply/sdk/types/utils

Readme

🚀 Droply SDK

High-performance compression and archive SDK with WASM-powered algorithms for Node.js, Web, and Bundler environments.

✨ Features

Multi-Platform Support: Works seamlessly in Node.js, browsers, and bundlers
WASM-Powered: High-performance compression using WebAssembly
TypeScript First: Full TypeScript support with comprehensive types
Tree-Shakable: Optimized for modern bundlers with code splitting
Auto-Detection: Automatically detects platform and optimizes accordingly
Multiple Formats: Support for gzip, brotli, zip, tar, and more

🎯 Supported Platforms

Platform	Environment	Optimizations
Node.js	CLI, Server, Desktop	File system integration, Worker threads
Web	Browser, PWA	Streaming, SIMD, Mobile optimizations
Bundler	Next.js, Vite, Webpack	Tree-shaking, Code splitting, HMR

📦 Installation

# Install the main SDK
npm install @droply/sdk

# Install WASM plugins (required)
npm install @droply/plugins

🚀 Quick Start

Basic Usage

import { DroplySDK } from '@droply/sdk';

// Auto-detect platform and create SDK instance
const sdk = new DroplySDK();

// Compress data
const compressed = await sdk.compress(data, 'gzip', { level: 9 });

// Decompress data
const decompressed = await sdk.decompress(compressed, 'gzip');

Platform-Specific Usage

Node.js Environment

import { DroplyNode } from '@droply/sdk/node';

const nodeSDK = new DroplyNode();

// File system operations
const result = await nodeSDK.compressFilesFromDisk(
  ['file1.txt', 'file2.txt'],
  'output.zip',
  { algorithm: 'zip', level: 6 }
);

Web Environment

import { DroplyWeb } from '@droply/sdk/web';

const webSDK = new DroplyWeb();

// Browser-optimized operations
const result = await webSDK.compress(data, 'brotli', { quality: 11 });

Bundler Environment (Next.js, Vite, etc.)

import { DroplyBundler } from '@droply/sdk/bundler';

const bundlerSDK = new DroplyBundler();

// Bundler-optimized operations with tree-shaking
const result = await bundlerSDK.processFilesOptimized(files, options);

🔧 API Reference

Core SDK Class

class DroplySDK {
  // Compression
  compress(data: Uint8Array, algo: CompressionAlgo, options?: ProcessOptions): Promise<Uint8Array>
  decompress(data: Uint8Array, algo: CompressionAlgo): Promise<Uint8Array>
  
  // Archiving
  createArchive(files: FileTuple[], algo: ArchiveAlgo, options?: ProcessOptions): Promise<Uint8Array>
  extractArchive(data: Uint8Array, algo: ArchiveAlgo): Promise<FileTuple[]>
  
  // File processing
  processFiles(files: FileTuple[], options?: ProcessOptions): Promise<ProcessResult>
  processFilesMeta(files: FileTuple[], options?: ProcessOptions): Promise<ProcessResult>
  
  // Platform detection
  getPlatform(): PlatformInfo
}

Platform-Specific Classes

DroplyNode (Node.js)

class DroplyNode extends DroplySDK {
  compressFilesFromDisk(filePaths: string[], outputPath: string, options?: ProcessOptions): Promise<Result>
  extractArchiveToDisk(archivePath: string, outputDir: string, options?: ProcessOptions): Promise<Result>
  getNodeInfo(): NodeInfo
}

DroplyWeb (Browser)

class DroplyWeb extends DroplySDK {
  loadWasmFromUrl(url: string, options?: LoadOptions): Promise<WebAssembly.Module>
  detectBrowserCapabilities(): BrowserCapabilities
  getMobileInfo(): MobileInfo
}

DroplyBundler (Next.js, Vite, Webpack)

class DroplyBundler extends DroplySDK {
  loadWasmModule(moduleName: string, options?: LoadOptions): Promise<WebAssembly.Module>
  processFilesOptimized(files: FileTuple[], options?: ProcessOptions): Promise<OptimizedResult>
  getBundlerInfo(): BundlerInfo
  preloadCommonModules(): Promise<void>
}

📁 File Structure

@droply/sdk/
├── index.js          # Main SDK (auto-detects platform)
├── node.js           # Node.js specific optimizations
├── web.js            # Web browser optimizations
├── bundler.js        # Bundler optimizations
├── utils/            # Utility functions
│   ├── compressor.js # Compression utilities
│   ├── archiver.js   # Archive utilities
│   └── extensions.js # File extension utilities
└── types/            # TypeScript definitions
    └── index.d.ts    # All type definitions

🔌 WASM Integration

The SDK automatically integrates with @droply/plugins for WASM modules:

// WASM modules are automatically loaded based on platform
const sdk = new DroplySDK();

// Platform-specific WASM paths:
// - Node.js: ./plugins/nodejs/compression/gzip/
// - Web: ./plugins/web/compression/gzip/
// - Bundler: ./plugins/bundler/compression/gzip/

⚙️ Configuration

import { DroplySDK, DEFAULT_SDK_CONFIG } from '@droply/sdk';

const config = {
  ...DEFAULT_SDK_CONFIG,
  platform: 'auto',        // 'auto' | 'node' | 'web' | 'bundler'
  timeout: 60000,          // 60 seconds
  maxMemory: 2 * 1024 * 1024 * 1024, // 2GB
  enableLogging: true,
  preloadModules: true,
  workerThreads: 8,
};

const sdk = new DroplySDK(config);

🧪 Testing

// Test platform detection
const platform = sdk.getPlatform();
console.log(`Platform: ${platform.type}`);
console.log(`Features: ${platform.features.join(', ')}`);

// Test compression
const testData = new TextEncoder().encode('Hello, World!');
const compressed = await sdk.compress(testData, 'gzip');
const decompressed = await sdk.decompress(compressed, 'gzip');

console.log('Test passed:', new TextDecoder().decode(decompressed) === 'Hello, World!');

🚀 Performance Tips

For Node.js

Use worker threads for large files: { parallel: true, workers: 4 }
Enable preloading: { preloadModules: true }
Use appropriate compression levels: { level: 6 } (balanced)

For Web

Enable streaming: { streaming: true }
Use appropriate quality settings: { quality: 11 } for brotli
Preload common modules in production

For Bundlers

Use tree-shaking: Import only what you need
Enable code splitting for large WASM modules
Use dynamic imports for better performance

🔍 Troubleshooting

Common Issues

WASM modules not found

# Make sure plugins are built
cd wasm/packages/_plugins
./build.sh build

Platform detection fails

// Force platform
const sdk = new DroplySDK({ platform: 'node' });

Memory errors

// Increase memory limit
const sdk = new DroplySDK({ maxMemory: 4 * 1024 * 1024 * 1024 });

Debug Mode

const sdk = new DroplySDK({ 
  enableLogging: true,
  enableMetrics: true 
});

// Check platform info
console.log(sdk.getPlatform());

📚 Examples

CLI Tool (Node.js)

import { DroplyNode } from '@droply/sdk/node';

const cli = new DroplyNode();

async function main() {
  const files = process.argv.slice(2);
  if (files.length === 0) {
    console.log('Usage: node cli.js <file1> <file2> ...');
    return;
  }
  
  const result = await cli.compressFilesFromDisk(files, 'output.zip');
  console.log(`Compressed ${result.stats.filesProcessed} files`);
}

Web App (React/Next.js)

import { DroplyBundler } from '@droply/sdk/bundler';
import { useState } from 'react';

export function CompressionApp() {
  const [sdk] = useState(() => new DroplyBundler());
  const [result, setResult] = useState(null);
  
  const handleFileUpload = async (files: FileList) => {
    const fileTuples = Array.from(files).map(file => ({
      name: file.name,
      data: new Uint8Array(await file.arrayBuffer())
    }));
    
    const compressed = await sdk.processFilesOptimized(fileTuples, { algorithm: 'zip' });
    setResult(compressed);
  };
  
  return (
    <div>
      <input type="file" multiple onChange={(e) => handleFileUpload(e.target.files)} />
      {result && <div>Compressed: {result.stats.compressionRatio.toFixed(1)}%</div>}
    </div>
  );
}

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

MIT License - see LICENSE for details.

🆘 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: GitHub Wiki

Made with ❤️ by ZamDev