Features

• 🌐 Universal — Works in React, Vue, Svelte, Node.js, and any JavaScript environment
• 📁 Flexible Uploads — Accepts browser File, Blob, Node.js Buffer, or file paths
• 📊 Upload Progress — Real-time progress callbacks
• 🔄 Chunked / Resumable Uploads — Upload large files in shards with resume support
• ⬇️ Download Files — Download file content directly as ArrayBuffer
• 🔁 Auto Retry — Automatic exponential backoff on network failures & 5xx errors
• 🛡️ Typed Errors — Structured AsyncError with HTTP status codes & error codes
• 📝 TypeScript — Full type definitions with JSDoc on every method

Installation

npm install codxell-async

Quick Start

Browser (React, Vue, etc.)

import { AsyncClient } from "codxell-async";

const client = new AsyncClient({
  apiKey: "ak_your_api_key_here",
});

// Upload from <input type="file">
const fileInput = document.querySelector("input[type=file]");
const data = await client.upload(fileInput.files[0]);

console.log(data.fileId); // "abc-123"
console.log(data.name); // "photo.png"
console.log(data.mimeType); // "image/png"
console.log(data.size); // 204800

Node.js

import { AsyncClient } from "codxell-async";

const client = new AsyncClient({ apiKey: "ak_..." });

// Upload from file path
const data = await client.upload("./photo.png");

// Upload from Buffer
const buffer = fs.readFileSync("./doc.pdf");
const data = await client.upload(buffer, "doc.pdf");

Configuration

const client = new AsyncClient({
  apiKey: "ak_...", // API key authentication
  // bearerToken: "jwt_...",    // OR JWT authentication
  baseUrl: "https://...", // Default: https://async.codxell.com
  timeout: 30000, // Request timeout in ms (default: 30s)
  maxRetries: 2, // Auto retries on failure (default: 2)
});

API Reference

Upload

// Browser File
const data = await client.upload(file);

// Browser File with progress
const data = await client.upload(file, file.name, {
  onProgress: (percent) => console.log(`${percent}%`),
});

// Node.js file path
const data = await client.upload("./image.png");

// Buffer (Node.js) or Blob (Browser)
const data = await client.upload(blob, "file.txt");

Returns: FileData with fileId, name, size, extension, mimeType, etc.

List Files

const files = await client.list();

files.forEach((f) => {
  console.log(f.name, f.extension, f.mimeType);
  console.log(AsyncClient.formatSize(f.size)); // "2.50 MB"
});

Get File Metadata

const meta = await client.getMeta("file-id");
// { fileId, name, size, extension, mimeType, createdAt, uploadStatus, ... }

Delete File

const deleted = await client.delete("file-id");

Download File

// Download as ArrayBuffer
const buffer = await client.download("file-id");

// Browser: save to disk
const blob = new Blob([buffer]);
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "filename.png";
a.click();

URLs

// Direct download URL (for <a href> or fetch)
const url = client.getDownloadUrl("file-id");

// Thumbnail URL (for <img src>)
const thumb = client.getThumbnailUrl("file-id");

Chunked / Resumable Uploads

For large files, upload in shards with resume support:

import { v4 as uuidv4 } from "uuid";

const fileId = uuidv4();
const shardSize = 10 * 1024 * 1024; // 10 MB

// Upload each shard
for (let i = 0; i < totalShards; i++) {
  const chunk = file.slice(i * shardSize, (i + 1) * shardSize);
  const base64 = btoa(String.fromCharCode(...new Uint8Array(chunk)));
  await client.uploadShard(fileId, i, base64, file.name);
}

// Finalize
await client.finalizeUpload(fileId, file.name);

// Check progress (for resume)
const { uploaded } = await client.getUploadStatus(fileId);

// Cancel if needed
await client.cancelUpload(fileId);

Error Handling

All errors are thrown as AsyncError with structured information:

import { AsyncClient, AsyncError } from "codxell-async";

try {
  await client.delete("non-existent-id");
} catch (err) {
  if (err instanceof AsyncError) {
    console.log(err.message); // "Not found"
    console.log(err.status); // 404
    console.log(err.code); // "NOT_FOUND"
  }
}

| Code | Status | Meaning | | ---------------- | ------ | ---------------------------------- | | AUTH_FAILED | 401 | Invalid or missing API key / token | | FORBIDDEN | 403 | Access denied | | NOT_FOUND | 404 | File doesn't exist | | FILE_TOO_LARGE | 413 | File exceeds size limit | | RATE_LIMITED | 429 | Too many requests (auto-retried) | | SERVER_ERROR | 5xx | Server error (auto-retried) |

Utilities

// Human-readable file sizes
AsyncClient.formatSize(204800); // "200.00 KB"
AsyncClient.formatSize(1073741824); // "1.00 GB"

License

MIT © Codxell