MEGAJS

https://mega.js.org/docs/1.0/
Admin
MEGAJS is a JavaScript library for Node.js and browsers that handles MEGA encryption, file and...
Tokens:20,733
Snippets:226
Trust Score:8.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize Storage in various environments

Source: https://mega.js.org/docs/1.0/tutorial/login

Examples for authenticating using the Storage class in Node.js ESM, Node.js CJS, Browser, and Deno.

```javascript
import { Storage } from 'megajs'  
  
const storage = new Storage({  
  email: 'user@example.com',  
  password: 'correct horse battery example',  
  userAgent: 'ExampleApplication/1.0'  
})  
  
// Will resolve once the user is logged in  
// or reject if some error happens  
await storage.ready
```

```javascript
const { Storage } = require('megajs')  
  
// Node doesn't support top-level await when using CJS  
;(async function () {  
  const storage = new Storage({  
    email: 'user@example.com',  
    password: 'correct horse battery example',  
    userAgent: 'ExampleApplication/1.0'  
  })  
  
  // Will resolve once the user is logged in  
  
  // or reject if some error happens  
  await storage.ready  
}()).catch(error => {  
  console.error(error)  
  process.exit(1)  
})
```

```javascript
import { Storage } from 'https://unpkg.com/megajs/dist/main.browser-es.mjs'  
  
const storage = new Storage({  
  email: 'user@example.com',  
  password: 'correct horse battery example',  
  userAgent: 'ExampleApplication/1.0'  
})  
  
// Will resolve once the user is logged in  
// or reject if some error happens  
await storage.ready
```

```javascript
import { Storage } from 'npm:megajs'  
  
const storage = new Storage({  
  email: 'user@example.com',  
  password: 'correct horse battery example',  
  userAgent: 'ExampleApplication/1.0'  
})  
  
// Will resolve once the user is logged in  
// or reject if some error happens  
await storage.ready
```

--------------------------------

### Install via package managers

Source: https://mega.js.org/docs/1.0/tutorial/install

Use these commands to add the library to your project dependencies.

```bash
npm install megajs
```

```bash
yarn add megajs
```

```bash
pnpm add megajs
```

--------------------------------

### Download file via streams

Source: https://mega.js.org/docs/1.0/tutorial/downloading

Use .download() to obtain a Node.js stream for memory-efficient file handling. These examples demonstrate piping, event listeners, and async iteration.

```javascript
const stream = file.download()  
stream.on('error', error => console.error(error))  
stream.pipe(fs.createWriteStream(file.name))
```

```javascript
const stream = file.download()  
stream.on('error', error => console.error(error))  
stream.on('data', data => console.log(data))  
stream.on('end', () => console.log('finished'))
```

```javascript
const stream = file.download()  
try {  
  for await (const data of stream) {  
    console.log(data)  
  }  
  console.log('finished')  
} catch (error) {  
  console.error(error)  
}
```

--------------------------------

### Common file operations using promises

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Examples of sharing, renaming, moving, and deleting files using promise-based syntax.

```javascript
// Shares a file  
const sharedLink = await file.link()  
console.log(sharedLink)  
  
// Renames a file  
await file.rename('A whole new name.txt')  
  
// Moves a file to other directory  
const otherDirectory = storage.find('Other Directory')  
await file.moveTo(otherDirectory)  
  
// Moves a file to the trash bin  
await file.delete()  
  
// Deletes a file permanently  
await file.delete(true)  
```

--------------------------------

### Callback-based file sharing

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Example of using a callback function to handle the result of a file sharing operation.

```javascript
// The first example above using callbacks  
file.link((error, link) => {  
  if (error) throw error  
  console.log(link)  
})  
```

--------------------------------

### Resume interrupted download in Node.js

Source: https://mega.js.org/docs/1.0/tutorial/interrupted-downloads

Uses fs.statSync to determine the current file size and resumes the download by setting the start offset in the download and write streams.

```javascript
const file = File.fromURL(url)  
await file.loadAttributes()  
  
const start = fs.statSync(file.name).size  
const downloadStream = file.download({ start })  
  
const writableStream = fs.createWriteStream(filename, {  
  flags: 'r+', // <= set flags to prevent overwriting the file  
  start  
})  
  
downloadStream.pipe(writableStream)
```

--------------------------------

### Run Downloading Demo

Source: https://mega.js.org/docs/1.0/examples/file-downloading

Execute the demonstration script directly from the Mega.js server using the Deno runtime.

```bash
deno run https://mega.js.org/demos/downloading-demo.js  
```

--------------------------------

### Run the folder upload demo

Source: https://mega.js.org/docs/1.0/examples/advanced-folder-uploading

Execute the demonstration script directly via Deno.

```bash
deno run https://mega.js.org/demos/advanced-uploading-demo.js  
```

--------------------------------

### Initialize File Class

Source: https://mega.js.org/docs/1.0/api

Demonstrates how to instantiate the File class using different module systems and environments.

```javascript
import { File } from 'megajs'  
const fileFromUrl = File.fromURL(url)  
const fileFromObject = new File({ downloadId, key })  
```

```javascript
const { File } = require('megajs')  
const fileFromUrl = File.fromURL(url)  
const fileFromObject = new File({ downloadId, key })  
```

```javascript
import { File } from 'https://unpkg.com/megajs/dist/main.browser-es.mjs'  
const fileFromUrl = File.fromURL(url)  
const fileFromObject = new File({ downloadId, key })  
```

```javascript
import { File } from 'npm:megajs'  
const fileFromUrl = File.fromURL(url)  
const fileFromObject = new File({ downloadId, key })  
```

--------------------------------

### Run Uploading Demo

Source: https://mega.js.org/docs/1.0/examples/file-uploading

Execute the demonstration script directly from the Mega.js website using Deno.

```shell
deno run https://mega.js.org/demos/uploading-demo.js  
```

--------------------------------

### Run Streaming Download Demo

Source: https://mega.js.org/docs/1.0/examples/file-streaming

Execute the demonstration script directly from the Mega.js website using Deno.

```bash
deno run https://mega.js.org/demos/streaming-downloading-demo.js
```

--------------------------------

### Run Shared Downloading Demo

Source: https://mega.js.org/docs/1.0/examples/shared-file-downloading

Execute the demonstration script directly from the Mega.js website using the Deno runtime.

```bash
deno run https://mega.js.org/demos/shared-downloading-demo.js  
```

--------------------------------

### Run Custom Key Shared Folder Demo

Source: https://mega.js.org/docs/1.0/examples/custom-key-folder-share

Execute the demonstration script directly via Deno.

```bash
deno run https://mega.js.org/demos/custom-key-shared-folder-demo.js  
```

--------------------------------

### Run MegaJS logging-in demo

Source: https://mega.js.org/docs/1.0/examples/logging-in

Execute the demonstration script directly from the MegaJS website using Deno.

```bash
deno run https://mega.js.org/demos/logging-in-demo.js  
```

--------------------------------

### Await storage readiness

Source: https://mega.js.org/docs/1.0/tutorial/login

Shortcut to create and await the storage instance simultaneously.

```javascript
// Create and already wait for the storage to be ready at the same time  
const storage = await new Storage({ ... }).ready
```

--------------------------------

### Run Folder Upload Demo

Source: https://mega.js.org/docs/1.0/examples/folder-uploading

Execute the folder uploading demonstration directly from the remote source.

```shell
deno run https://mega.js.org/demos/folder-uploading-demo.js  
```

--------------------------------

### Run File Sharing Demo

Source: https://mega.js.org/docs/1.0/examples/file-sharing

Execute the demonstration script directly from the Mega.js website using Deno.

```shell
deno run https://mega.js.org/demos/sharing-demo.js  
```

--------------------------------

### Run Distribution Demo

Source: https://mega.js.org/docs/1.0/examples/project-distribution

Execute the project distribution demonstration directly from the remote source.

```bash
deno run https://mega.js.org/demos/project-distribution-demo.js
```

--------------------------------

### Run file iteration demo

Source: https://mega.js.org/docs/1.0/examples/iterating-files

Execute the demonstration script directly from the Mega.js website using Deno.

```shell
deno run https://mega.js.org/demos/iterating-files-demo.js  
```

--------------------------------

### Run Shared Streaming Demo

Source: https://mega.js.org/docs/1.0/examples/shared-file-streaming

Execute the demonstration script directly from the remote URL using the Deno runtime.

```bash
deno run https://mega.js.org/demos/shared-streaming-demo.js  
```

--------------------------------

### Creating new folders

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Demonstrates creating a new directory using both promise and callback patterns.

```javascript
// Using promises  
const folder = await folder.mkdir('New Folder')  
console.log(folder)  
  
// Using callbacks  
folder.mkdir('New Folder', (error, folder) {  
  if (error) console.error(error)  
  console.log(folder)  
})  
```

--------------------------------

### Run Renaming Demo

Source: https://mega.js.org/docs/1.0/examples/file-renaming

Execute the demonstration script directly from the Mega JS website using Deno.

```shell
deno run https://mega.js.org/demos/renaming-demo.js  
```

--------------------------------

### Compare file access methods

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Demonstrates the evolution of file access patterns from manual traversal to the simplified navigate and find methods.

```javascript
// How to get the file "hello-world.txt" inside the file "My Folder" from the storage root:  
  
// --- Before v1.2.0  
storage.root.children.find(folder => folder.name === 'My Folder').children.find(file => file.name === 'hello-world.txt')  
  
// --- After v1.2.0  
storage.navigate('My Folder/hello-world.txt')  
  
  
// How to search files in the entire storage:  
  
// --- Before v1.2.0, using the `storage.files` object:  
Object.values(storage.files).find(file => file.name === 'hello-world.txt')  
  
// --- After v1.2.0, using `.find` in recursive mode:  
storage.find('hello-world.txt', true)
```

--------------------------------

### Run Upload Stream Demo

Source: https://mega.js.org/docs/1.0/examples/file-uploading-stream

Execute the demonstration script directly from the Mega.js demo repository.

```bash
deno run https://mega.js.org/demos/uploading-stream-demo.js  
```

--------------------------------

### Stream File Download to Local Disk

Source: https://mega.js.org/docs/1.0/examples/file-streaming

Demonstrates how to fetch a file from storage, open a local file stream, and pipe the download stream into it.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
const storage = await getLoggedInStorage()  
  
console.log('Choose one of the following files:')  
console.log(storage.root.children.filter(e => !e.children).map(e => e.name))  
  
const filename = prompt('Enter a file name (case sensitive):')  
const file = storage.find(filename)  
if (!file) throw Error('File not found!')  
  
const downloadStream = await file.download()  
  
// Open file for writing and get the writer  
const denoFile = await Deno.create(file.name)  
const writer = denoFile.writable.getWriter()  
  
// Iterate the download stream and write to the file  
for await (const data of downloadStream) {  
  await writer.write(data)  
}  
  
// Finally close the writer  
await writer.close()
```

--------------------------------

### File Class Initialization

Source: https://mega.js.org/docs/1.0/api

Methods for creating a File instance from a URL or a configuration object.

```APIDOC
## File.fromURL(url, options)

### Description
Creates a File instance from a shared MEGA URL.

### Parameters
- **url** (string) - Required - The shared MEGA URL (e.g., https://mega.nz/file/...). 
- **options** (object) - Optional - Configuration object containing an optional `api` instance.

## new File(options)

### Description
Creates a File instance from a configuration object.

### Parameters
- **options** (object) - Required
  - **downloadId** (string) - Required - The ID part of the share link.
  - **key** (string|Buffer) - Optional - The encryption key part of the share link.
  - **directory** (boolean) - Optional - Set to true if loading a shared folder.
  - **api** (object) - Optional - An authenticated API object.
```

--------------------------------

### Initialize Storage Connection

Source: https://mega.js.org/docs/1.0/api

Create a new Storage instance to authenticate and connect to MEGA. Choose the appropriate import method based on your runtime environment.

```javascript
import { Storage } from 'megajs'  
const storage = new Storage(options, [callback])  
```

```javascript
const { Storage } = require('megajs')  
const storage = new Storage(options, [callback])  
```

```javascript
import { Storage } from 'https://unpkg.com/megajs/dist/main.browser-es.mjs'  
const storage = new Storage(options, [callback])  
```

```javascript
import { Storage } from 'npm:megajs'  
const storage = new Storage(options, [callback])  
```

--------------------------------

### Run File Deletion Demo

Source: https://mega.js.org/docs/1.0/examples/file-deleting

Execute the demonstration script directly from the Mega JS website using Deno.

```shell
deno run https://mega.js.org/demos/delete-demo.js  
```

--------------------------------

### Initializing Storage with API Properties

Source: https://mega.js.org/docs/1.0/tutorial/network-settings

Pass API configuration properties directly into the Storage constructor.

```javascript
const storage = new Storage({  
  email: 'user@example.com',  
  password: 'correct horse battery example',  
  userAgent: 'ExampleClient/1.0'  
}, callback)
```

--------------------------------

### Run the Advanced File Downloader

Source: https://mega.js.org/docs/1.0/examples/advanced-file-downloader

Execute the script directly from the console using Deno, optionally providing a URL and configuration flags.

```bash
deno run https://mega.js.org/demos/advanced-file-downloader.js [URL] [...flags]
```

--------------------------------

### Initialize File with API Object

Source: https://mega.js.org/docs/1.0/api

Pass an API object to increase download limits when initializing a File instance.

```javascript
const fileFromUrl = File.fromURL(url, { api })  
const fileFromObject = new File({ downloadId, key, api })  
```

--------------------------------

### Run File Searching Demo

Source: https://mega.js.org/docs/1.0/examples/file-searching

Executes the file searching demonstration script directly from the Mega.js remote repository.

```shell
deno run https://mega.js.org/demos/file-searching-demo.js  
```

--------------------------------

### Create a new folder

Source: https://mega.js.org/docs/1.0/api

Creates a directory inside the current folder instance.

```javascript
await folder.mkdir('dirname')  
```

--------------------------------

### Upload a file with options

Source: https://mega.js.org/docs/1.0/tutorial/uploading

Configures the upload process by passing an options object as the first argument.

```javascript
const file = await storage.upload({  
  name: 'hello-world.txt'  
}, 'Hello world!').complete  
console.log('The file was uploaded!', file)  
```

--------------------------------

### Load via UMD script tag

Source: https://mega.js.org/docs/1.0/tutorial/install

Include the library in HTML files; it will be available under the window.mega namespace.

```html
<script src="https://unpkg.com/megajs@1/dist/main.browser-umd.js"></script>
```

--------------------------------

### Using Account Limits for Downloads

Source: https://mega.js.org/docs/1.0/tutorial/network-settings

Associate a file with a logged-in storage instance to utilize account-specific download limits.

```javascript
// First log in  
const storage = new Storage(options, callback)  
  
// Wait for the callback then get a shared file using the logged API  
const sharedFile = File.fromURL(url, {  
  api: storage.api  
})  
  
// Now downloading the shared file will use the limits from that account
```

--------------------------------

### .mkdir(options | name)

Source: https://mega.js.org/docs/1.0/api

Creates a new folder inside the current folder.

```APIDOC
## .mkdir(options | name)

### Description
Creates a new directory within the current folder context.

### Parameters
- **name** (string) - Required - Directory name
- **options** (object) - Optional - Configuration including attributes and encryption key.
```

--------------------------------

### Implement Custom Key Folder Sharing

Source: https://mega.js.org/docs/1.0/examples/custom-key-folder-share

Logic for selecting a folder and applying a custom 22-character key to generate a shareable link.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
const storage = await getLoggedInStorage()  
  
console.log('Choose one of the following folders:')  
console.log(storage.root.children.map(e => e.name))  
  
const filename = prompt('Enter a folder name (case sensitive):')  
const file = storage.find(filename)  
if (!file) throw Error('File not found!')  
if (!file.children) throw Error("That's not a folder!")  
  
let key  
for (let i = 0; i < 3; i++) {  
  console.log('Choose a key:')  
  console.log('(22 character string ending with A, Q, g or w)')  
  const choosenKey = prompt('>')  
  if (choosenKey && choosenKey.match(/^[A-Za-z\-_]{21}[AQgw]$/)) {  
    key = choosenKey  
    break  
  } else {  
    console.log('Invalid key')  
  }  
}  
if (!key) {  
  console.log('Key not choosen after three tries, using demo key:')  
  key = 'MidnightBlueCrayonDraw'  
}  
const link = await file.link({ key })  
console.log(link)  
```

--------------------------------

### Project Distribution Script

Source: https://mega.js.org/docs/1.0/examples/project-distribution

A complete Deno script to compress a local 'dist' folder, upload it to MEGA, and prune older files. Requires '7z' to be available in the system path.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
import * as path from 'https://deno.land/std@0.188.0/path/mod.ts'  
import prettyBytes from 'npm:pretty-bytes'  
import ProgressBar from 'https://deno.land/x/progress@v1.4.5/mod.ts'  
  
// Generate a 7z file by compressing a ../dist folder (requires 7z in the path)  
const buildName = new Date().toISOString().slice(0, 13) + '.7z'  
const buildPath = path.fromFileUrl(new URL('./' + buildName, import.meta.url))  
const rootPath = path.fromFileUrl(new URL('../dist', import.meta.url))  
const command = new Deno.Command('7z', {  
  args: ['a', buildPath, rootPath]  
})  
const { code, stderr } = await command.output()  
if (code !== 0) {  
  console.error(new TextDecoder().decode(stderr))  
  throw Error(`7z exited with ${code}`)  
}  
const data = await Deno.readFile(buildPath)  
console.log('Got a', data.length, 'byte (' + prettyBytes(data.length) + ') bundle')  
  
// Log in intro MEGA  
const storage = await getLoggedInStorage()  
  
// Try to find a folder where files will be shared  
const rootFolderName = 'Distributed files'  
let rootFolder = storage.find(rootFolderName)  
  
// If no folder is found, ask user if the script can create one  
if (!rootFolder) {  
  console.log('Root folder not found, create one?')  
  const promptResult = window.confirm('>')  
  if (!promptResult) throw Error('Aborted')  
      
  // If allowed, the script will create the folder and share it with a custom key  
  rootFolder = await storage.mkdir(rootFolderName)  
  const link = await rootFolder.link({ key: 'DeepSeaTreasureHunting' })  
  console.log('Base folder created and shared:', link)  
}  
  
// Prune folder  
if (rootFolder.children) {  
  // Sort files in the folder by timestamp, them remove the first most recent ones from the array  
  const childToDelete = rootFolder.children.slice().sort((a, b) => {  
    return b.timestamp - a.timestamp  
  }).slice(10)  
    
  // Them delete all files that remained  
  for (const entry of childToDelete) {  
    await entry.delete(true)  
  }  
    
  // Check if a duplicate file exists and, if so, delete it  
  const duplicateBuild = rootFolder.find(buildName)  
  if (duplicateBuild) await duplicateBuild.delete(true)  
}  
  
// Create a progress bar to track the upload progress  
const progressBar = new ProgressBar({  
  display: ':title :percent :bar :time/:eta',  
  title: 'Uploading ' + buildName + ':',  
  total: data.length  
})  
progressBar.render(0)  
  
// Upload the file  
const uploadStream = rootFolder.upload({  
  name: buildName,  
  // Seems that setting maxConnections to 1 improved results  
  maxConnections: 1  
}, data)  
  
// Handle progress events  
uploadStream.on('progress', event => {  
  progressBar.render(event.bytesUploaded)  
})  
  
// Create a timeout to handle bad network connections  
// (at the time I implemented this code my Internet connection was really bad)  
const maxTimeout = 36e5 // 60 minutes  
let timeoutTimer  
let exitCode = 0  
try {  
  await Promise.race([  
    uploadStream.complete,  
    new Promise((resolve, reject) => {  
      timeoutTimer = setTimeout(reject, maxTimeout, Error('Upload timeout out'))  
    })  
  ])  
  
  console.log('\n\n' + buildName, 'was uploaded')  
} catch (error) {  
  console.error(error)  
  exitCode = 1  
}  
  
// Clear up things  
clearTimeout(timeoutTimer)  
await storage.close().catch(() => { /* Ignore errors at this step */ })  
await Deno.remove(buildPath)  
Deno.exit(exitCode)
```

--------------------------------

### File and folder manipulation methods

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Overview of available methods for managing files and folders.

```javascript
fileORFolder.link() // shares files and folders  
fileORFolder.unshare() // unshares files and folders  
fileORFolder.rename(newName) // renames files and folders  
fileORFolder.moveTo(someFolder) // moves files and folders  
fileORFolder.setFavorite(true) // marks files and folders as favorites  
fileORFolder.delete() // moves files and folders to the trash  
fileORFolder.delete(true) // delete files and folders permanently   
```

--------------------------------

### Stream Shared File to Local Disk

Source: https://mega.js.org/docs/1.0/examples/shared-file-streaming

Initialize a file from a URL, handle directory traversal if necessary, and stream the file content to a local file using Deno's writable streams.

```javascript
import { File } from 'npm:megajs'  
  
// Get the shared file URL  
const url = prompt('Enter the URL of a shared MEGA file or folder:')  
  
// Create a File object  
const mainFile = File.fromURL(url)  
  
// Setup an user-agent  
mainFile.api.userAgent = 'MEGAJS-Demos (+https://mega.js.org/)'  
  
// Load attributes and get the selected file  
let selectedFile = await mainFile.loadAttributes()  
if (!selectedFile) throw Error('File not found!')  
  
// For links of folders pointing to a specific file the mainFile  
// will point to the folder and the selectedFile will point to  
// the file, for all other cases those two variables will be the same  
  
// Handle directories:  
if (selectedFile.children) {  
  console.log('It points to a directory, downloading the first file:')  
  const firstChild = selectedFile.find(node => !node.children, true)  
  if (!firstChild) throw Error('Folder have no children!')  
  selectedFile = firstChild  
}  
  
console.log('File info:')  
console.log(selectedFile)  
  
const downloadStream = await selectedFile.download()  
  
// Open file for writing and get the writer  
const denoFile = await Deno.create(selectedFile.name)  
const writer = denoFile.writable.getWriter()  
  
// Iterate the download stream and write to the file  
for await (const data of downloadStream) {  
  await writer.write(data)  
}  
  
// Finally close the writer  
await writer.close()
```

--------------------------------

### .upload(options | name, [data], [callback])

Source: https://mega.js.org/docs/1.0/api

Uploads a file to a folder. Supports buffers, strings, or streams as data input.

```APIDOC
## .upload(options | name, [data], [callback])

### Description
Uploads a file to a folder. You can provide data as a buffer, string, or stream, or pipe data into the returned stream.

### Parameters
- **name** (string) - Required - File name
- **data** (Buffer|string|stream) - Optional - File content
- **callback** (function) - Optional - Callback function receiving (error, uploadedFile)
- **options** (object) - Optional - Configuration object including attributes, key, size, thumbnailImage, previewImage, maxConnections, initialChunkSize, chunkSizeIncrement, maxChunkSize, handleRetries, and forceHttps.
```

--------------------------------

### Download Shared File via Mega.js

Source: https://mega.js.org/docs/1.0/examples/shared-file-downloading

Initialize a file object from a URL, handle directory traversal if necessary, and save the file buffer to the local disk.

```javascript
import { File } from 'npm:megajs'  
  
// Get the shared file URL  
const url = prompt('Enter the URL of a shared MEGA file or folder:')  
  
// Create a File object  
const mainFile = File.fromURL(url)  
  
// Setup an user-agent  
mainFile.api.userAgent = 'MEGAJS-Demos (+https://mega.js.org/)'  
  
// Load attributes and get the selected file  
let selectedFile = await mainFile.loadAttributes()  
  
// For links of folders pointing to a specific file the mainFile  
// will point to the folder and the selectedFile will point to  
// the file, for all other cases those two variables will be the same  
  
// Handle directories:  
if (selectedFile.children) {  
  console.log('It points to a directory, downloading the first file:')  
  const firstChild = selectedFile.find(node => !node.children, true)  
  if (!firstChild) throw Error('Folder have no children!')  
  selectedFile = firstChild  
}  
  
// Show some info about the file to the user  
console.log('File info:')  
console.log(selectedFile)  
  
// Download everything into a variable  
const data = await selectedFile.downloadBuffer()  
  
// Then save to the file  
await Deno.writeFile(selectedFile.name, data)  
```

--------------------------------

### Implement reusable login function

Source: https://mega.js.org/docs/1.0/examples/logging-in

Define a function to initialize storage using environment variables, designed for reuse across multiple demo scripts.

```typescript
import { Storage } from 'npm:megajs'  
  
// Export this function so it will be reused in other demos  
export function getLoggedInStorage () {  
  // Get credentials from environment variables  
  // Don't worry: Deno will prompt if you allow the code to read those variables  
  const email = Deno.env.get('MEGA_EMAIL')  
  const password = Deno.env.get('MEGA_PASSWORD')  
  
  // Set up a user-agent  
  const userAgent = 'MEGAJS-Demos (+https://mega.js.org/)'  
  
  // Create a new storage and return its ready promise  
  // (the .ready promise resolves to the storage itself when it's ready  
  // so it's a nice shortcut to avoid having to handle the ready event)  
  return new Storage({ email, password, userAgent }).ready  
}  
  
// Run the below code only if this code is run directly  
if (import.meta.main) {  
  const storage = await getLoggedInStorage()  
  console.log(storage)  
}  
```

--------------------------------

### .link() / .shareFolder()

Source: https://mega.js.org/docs/1.0/api

Generates a download link for a file or folder.

```APIDOC
## .link() / .shareFolder()

### Description
Creates a shareable download link. .shareFolder is for folders, .link works for both.

### Parameters
- **options** (object) - Optional - Includes noKey (boolean) and key (string|buffer).
```

--------------------------------

### .download([options], [callback])

Source: https://mega.js.org/docs/1.0/api

Downloads and decrypts file contents into a readable stream or a buffer if a callback is provided. It uses chunked parallel connections to optimize download speeds.

```APIDOC
## .download([options], [callback])

### Description
Downloads and decrypts file contents. Supports progress events via the 'progress' event.

### Parameters
- **options** (object) - Optional - Configuration for download: maxConnections, initialChunkSize, chunkSizeIncrement, maxChunkSize, returnCiphertext, handleRetries, forceHttps, start, end.
- **callback** (function) - Optional - Callback function receiving (err, data).
```

--------------------------------

### .downloadBuffer([options])

Source: https://mega.js.org/docs/1.0/api

A wrapper for .download() that returns a Promise resolving to a Buffer containing the file data.

```APIDOC
## .downloadBuffer([options])

### Description
Wraps the .download() function and returns a Promise which resolves to a Buffer containing the file data. Accepts the same options as .download().
```

--------------------------------

### Share a file from storage

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Access the root folder and share the first file found in the account.

```javascript
// storage is the new Storage() class from the login tutorial  
  
// It will share the first file in the root folder of the account   
storage.root.children[0].link()
```

--------------------------------

### .navigate(query)

Source: https://mega.js.org/docs/1.0/api

Traverses directories using a path string or an array of path segments.

```APIDOC
## .navigate(query)

### Description
Traverses directories. Query can be a string with a '/' delimited path or an array of strings.

### Parameters
- **query** (string|array) - Required - The path to navigate to.
```

--------------------------------

### Storage Class

Source: https://mega.js.org/docs/1.0/api

The Storage class is the primary entry point for creating a logged-in connection instance to MEGA.

```APIDOC
## Storage Class

### Description
Creates a logged-in connection instance to MEGA. This class manages the session, file structure, and account-level operations.

### Constructor
`new Storage(options, [callback])`

### Options
- **email** (string) - Required - User login email.
- **password** (string) - Required - User password.
- **secondFactorCode** (string) - Optional - User two-factor authentication code.
- **keepalive** (boolean) - Optional - Keep connection open to receive server-to-client requests. Defaults to true.
- **autologin** (boolean) - Optional - Automatically login to MEGA. Defaults to true.
- **autoload** (boolean) - Optional - Automatically load file structure. Defaults to true.

### Methods
- **reload()**: Reloads the files tree.
- **login()**: Logins to MEGA.
- **getAccountInfo()**: Returns account and quota usage information.
- **close()**: Logs out of MEGA and closes the server-to-client connection.
```

--------------------------------

### File.fromURL(url, [options])

Source: https://mega.js.org/docs/1.0/api

Creates a File object based on a shared file or folder URL. Accepts an optional options object with an api object.

```APIDOC
## File.fromURL(url, [options])

### Description
Creates a File object based on a shared file or folder URL.

### Parameters
- **url** (string) - Required - The shared file or folder URL.
- **options** (object) - Optional - An object containing an api property.
```

--------------------------------

### Import via ES modules

Source: https://mega.js.org/docs/1.0/tutorial/install

Load the library directly in browser environments using a CDN.

```javascript
import { Storage } from 'https://cdn.skypack.dev/megajs'
```

--------------------------------

### Download file as buffer

Source: https://mega.js.org/docs/1.0/tutorial/downloading

Use .downloadBuffer() to retrieve the entire file content into memory. This supports both promises and callback patterns.

```javascript
// Using promises  
const data = await file.downloadBuffer()  
  
// data is a Buffer containing the file contents  
console.log(data)  
  
// Using callbacks  
file.downloadBuffer((error, data) => {  
  if (error) console.error(error)  
  console.log(data)  
})
```

--------------------------------

### Use constructor callback for authentication

Source: https://mega.js.org/docs/1.0/tutorial/login

Pass a callback function to the constructor to handle login results.

```javascript
const storage = new Storage({  
  email: 'user@example.com',  
  password: 'correct horse battery example',  
  userAgent: 'ExampleClient/1.0'  
}, error => {  
  if (error) {  
    // Some error happened  
  } else {  
    // User is now logged in  
  }  
})
```

--------------------------------

### Generate a download link

Source: https://mega.js.org/docs/1.0/api

Creates a shareable download URL for a file or folder.

```javascript
// Returns something like https://mega.nz/#!downloadId!key  
const url = await file.link()  
```

--------------------------------

### verify(fileKey)

Source: https://mega.js.org/docs/1.0/api

Creates a PassThrough stream that verifies the content received against the provided file key.

```APIDOC
## verify(fileKey)

### Description
Creates a PassThrough stream that verifies the content received against the provided file key. The function emits 'end' when the file is valid and 'error' if the file is corrupted.

### Parameters
- **fileKey** (string | Buffer | Uint8Array) - Required - The file key used for verification, typically extracted from the share link.
```

--------------------------------

### Download File from Mega Storage

Source: https://mega.js.org/docs/1.0/examples/file-downloading

Authenticate, select a file by name, and save its contents to the local disk. Requires a valid session from the logging-in-demo module.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
const storage = await getLoggedInStorage()  
  
console.log('Choose one of the following files:')  
console.log(storage.root.children.filter(e => !e.children).map(e => e.name))  
  
const filename = prompt('Enter a file name (case sensitive):')  
const file = storage.find(filename)  
if (!file) throw Error('File not found!')  
  
const data = await file.downloadBuffer()  
await Deno.writeFile(file.name, data)  
```

--------------------------------

### Implement recursive folder upload

Source: https://mega.js.org/docs/1.0/examples/advanced-folder-uploading

This script uses Deno's file system API to read directories and stream file contents to MEGA. It requires appropriate read permissions to access the local file system.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
import { basename, join } from 'https://deno.land/std@0.224.0/path/mod.ts'  
const storage = await getLoggedInStorage()  
  
const directoryName = basename(Deno.cwd())  
const baseFolder = storage.find(directoryName) ?? await storage.mkdir(directoryName)  
  
await uploadDirectory(baseFolder, Deno.cwd())  
  
async function uploadDirectory (megaFolder, folderPath) {  
  for await (const entry of Deno.readDir(folderPath)) {  
    if (entry.isDirectory) {  
      const childFolder = await megaFolder.mkdir(entry.name)  
      await uploadDirectory(childFolder, join(folderPath, entry.name))  
    } else {  
      await uploadFile(megaFolder, folderPath, entry.name)  
    }  
  }  
}  
  
async function uploadFile (megaFolder, folderPath, name) {  
  const uploadStream = megaFolder.upload({ name })  
  
  // Get the file and its reader  
  const denoFile = await Deno.open(join(folderPath, name))  
  const inputReader = denoFile.readable.getReader()  
  
  // Read the file and pass the data to the upload stream  
  // (it's a Node.js Writable stream)  
  while (true) {  
    const result = await inputReader.read()  
  
    if (result.value) {  
      const canContinueWritting = uploadStream.write(result.value)  
      if (!canContinueWritting) {  
        // Upload stream is under pressure, wait it to drain  
        await new Promise(resolve => uploadStream.once('drain', resolve))  
      }  
    }  
      
    if (result.done) {  
      // End the stream when there is no more data to be read  
      uploadStream.end()  
  
      // And break out the while loop  
      break  
    }  
  }  
  
  // Wait for the upload to complete and get the new file object  
  await uploadStream.complete  
}
```

--------------------------------

### Advanced File Downloader Implementation

Source: https://mega.js.org/docs/1.0/examples/advanced-file-downloader

A complete script for downloading files and folders with support for progress bars, filtering, and interrupted download resumption.

```javascript
import { File, verify } from 'npm:megajs'  
import { join } from 'https://deno.land/std@0.224.0/path/mod.ts'  
import { parseArgs } from 'jsr:@std/cli/parse-args'  
import ProgressBar from 'https://deno.land/x/progress@v1.4.5/mod.ts'  
import { orderBy } from 'npm:natural-orderby'  
  
// Get the shared file URL from Deno.args or by prompting  
const args = parseArgs(Deno.args, { collect: ['filter', 'ignore'], boolean: ['verbose'] })  
const url = args._[0] ?? prompt('Enter the URL of a shared MEGA file or folder:')  
  
// Create a File object  
const mainFile = File.fromURL(url)  
  
// Setup an user-agent  
mainFile.api.userAgent = 'MEGAJS-Demos (+https://mega.js.org/)'  
  
// Load attributes and get the selected file  
const selectedNode = await mainFile.loadAttributes()  
  
// Download the file  
if (!selectedNode.name) throw Error('You should include the decryption key!')  
await downloadFile(selectedNode, args.dir ?? Deno.cwd())  
  
async function downloadFile (megaFile, folderPath) {  
  // Checks for directory nodes  
  if (megaFile.directory) {  
    // Create a new directory or use an existent one  
    const childFolderPath = join(folderPath, megaFile.name)  
    const childFolderStats = await Deno.stat(childFolderPath).catch(() => null)  
    if (!childFolderStats) {  
      await Deno.mkdir(childFolderPath)  
    } else if (!childFolderStats.isDirectory) {  
      throw Error(childFolderPath + ' is not a directory!')  
    }  
      
    // Sort children to avoid files being downloaded in a weird order  
    const sortedChildren = orderBy(megaFile.children, e => e.name)  
  
    // Download files into it  
    for (const child of sortedChildren) {  
      await downloadFile(child, childFolderPath)  
    }  
    return  
  }  
  
  // Handle filters (files need to match all filters)  
  if (args.filter) {  
    for (const filter of args.filter) {  
      if (!megaFile.name.includes(filter)) {  
        if (args.verbose) console.log(megaFile.name, 'does not match filter')  
        return  
      }  
    }  
  }  
  // Handle ignores (files need to not match all ignores)  
  if (args.ignore) {  
    for (const ignore of args.ignore) {  
      if (megaFile.name.includes(ignore)) {  
        if (args.verbose) console.log(megaFile.name, 'matches ignore filter')  
        return  
      }  
    }  
  }  
  
  // Check the file stats in order to handle finished or interrupted downloads  
  const filePath = join(folderPath, megaFile.name)  
  const fileStats = await Deno.stat(filePath).catch(() => null)  
  
  // Skip if there is no data left to download  
  if (fileStats && fileStats.size >= megaFile.size) {  
    if (args.verbose) console.log(megaFile.name, 'was already downloaded')  
    return  
  }  
  
  console.log('Downloading', megaFile.name, 'into', '"' + folderPath + '"')  
  if (fileStats) console.log('Continuing interrupted download at', fileStats.size, 'bytes')  
  
  // Open file for writing and get the writer  
  const denoFile = fileStats  
    ? await Deno.open(filePath, { append: true })  
    : await Deno.create(filePath)  
  const writer = denoFile.writable.getWriter()  
    
  // Create a progress bar to track the download progress  
  const progressBar = new ProgressBar({  
    display: ':percent :bar :time/:eta',  
    total: megaFile.size  
  })  
  progressBar.render(0)  
  
  const downloadStream = await megaFile.download({  
    // Start is needed to handle interrupted downloads  
    start: fileStats ? fileStats.size : 0  
  })  
    
  // Handle progress events  
  downloadStream.on('progress', event => {  
    progressBar.render(event.bytesLoaded)  
  })  
  
  // Iterate the download stream and write to the file  
  for await (const data of downloadStream) {  
    await writer.write(data)  
  }  
  
  // Finally close the writer  
  await writer.close()  
  
  // Verify the file if the download started mid-file  
  if (fileStats) {  
    const isFileValid = await verifyFile(filePath, megaFile)  
    if (isFileValid) {
```

--------------------------------

### Uploading files to a folder

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Upload a file to a specific folder using the .complete property.

```javascript
await folder.upload('hello-world.txt', 'Hello World!').complete  
```

--------------------------------

### Upload a file using promises

Source: https://mega.js.org/docs/1.0/tutorial/uploading

Uploads a file by providing a name and content, accessing the result via the .complete property.

```javascript
const file = await storage.upload('hello-world.txt', 'Hello world!').complete  
console.log('The file was uploaded!', file)  
```

--------------------------------

### Import in Deno

Source: https://mega.js.org/docs/1.0/tutorial/install

Use the npm specifier to import the library in Deno environments.

```typescript
import { Storage } from 'npm:megajs'
```

--------------------------------

### Share a file using link()

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Generate a shareable link for a file object using either promises or callbacks.

```javascript
// Using promises  
const link = await file.link()  
  
// It will log something like https://mega.nz/file/example#example  
console.log(link)  
  
// Using callbacks  
file.link((error, link) => {  
  if (error) console.error(error)  
  console.log(link)  
})
```

--------------------------------

### Search files with storage.find()

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Use the storage.find helper method to search for files by name or predicate, with optional recursive support.

```javascript
// Both examples searches files named "hello-world.txt"  
storage.find('hello-world.txt')  
storage.find(file => file.name === 'hello-world.txt')  
  
// Returns the first .jpeg or .jpg file from the storage root  
storage.find(file => file.name.match(/\.jpe?g$/i))  
  
// Set the second parameter to true to make it search recursively  
storage.find('hello-world.txt', true)  
  
// You can call it in any folder:  
storage.find('some folder').find('some other folder').find('some file.txt')
```

--------------------------------

### Stream File Upload Implementation

Source: https://mega.js.org/docs/1.0/examples/file-uploading-stream

Reads a local file using Deno and pipes the data into a Mega.js upload stream, handling backpressure with the 'drain' event.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
const storage = await getLoggedInStorage()  
  
// Open the file to be read  
const name = prompt('Enter a file name:')  
const denoFile = await Deno.open(name)  
  
const uploadStream = storage.upload({ name })  
  
// Get the file reader  
const inputReader = denoFile.readable.getReader()  
  
// Read the file and pass the data to the upload stream  
// (it's a Node.js Writable stream)  
while (true) {  
  const result = await inputReader.read()  
  
  if (result.value) {  
    const canContinueWritting = uploadStream.write(result.value)  
    if (!canContinueWritting) {  
      // Upload stream is under pressure, wait it to drain  
      await new Promise(resolve => uploadStream.once('drain', resolve))  
    }  
  }  
    
  if (result.done) {  
    // End the stream when there is no more data to be read  
    uploadStream.end()  
  
    // And break out the while loop  
    break  
  }  
}  
  
// Wait for the upload to complete and get the new file object  
const file = await uploadStream.complete  
console.log('The file was uploaded!', file)  
```

--------------------------------

### Filter Storage Files

Source: https://mega.js.org/docs/1.0/examples/file-searching

Demonstrates how to retrieve storage contents and filter them by file extension or specific filename using the filter method.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
const storage = await getLoggedInStorage()  
  
console.log('Those are all .jpeg files in the storage:')  
console.log(storage.filter(e => e.name.endsWith('.jpeg'), true))  
  
console.log('Those are all README files in the storage:')  
console.log(storage.filter('README', true))  
```

--------------------------------

### .moveTo(target)

Source: https://mega.js.org/docs/1.0/api

Moves a file to a target folder.

```APIDOC
## .moveTo(target)

### Description
Moves the file to the specified target folder or nodeId.

### Parameters
- **target** (object|string) - Required - The target folder object or nodeId.
```

--------------------------------

### Accessing the API Object

Source: https://mega.js.org/docs/1.0/tutorial/network-settings

Retrieve the API instance from a File or Storage object.

```javascript
// Get a File or Storage object  
const file = File.fromURL(url)  
const storage = new Storage(options, callback)  
  
// The API object can be accessed using:  
const api = file.api // or storage.api
```

--------------------------------

### Legacy migration pattern

Source: https://mega.js.org/docs/1.0/tutorial/login

Legacy pattern for migrating from tonistiigi's mega library, though not recommended for future use.

```javascript
const mega = require('megajs')  
  
const storage = mega({  
  email: 'user@example.com',  
  password: 'correct horse battery example'  
}, error => {  
  if (error) {  
    // Some error happened  
  } else {  
    // User is now logged in  
  }  
})
```

--------------------------------

### Navigate Directory Paths

Source: https://mega.js.org/docs/1.0/api

Traverses directory structures using slash-delimited strings or arrays of path segments.

```javascript
// Returns a file named `test.txt` inside "some folder"  
folder.navigate('some folder/test.txt')  
  
// Paths can also be defined as arrays of strings  
folder.navigate(['some folder', 'test.txt'])
```

--------------------------------

### Navigate deep file paths

Source: https://mega.js.org/docs/1.0/tutorial/handling-files

Use the navigate method to traverse deep folder structures or handle names containing slashes.

```javascript
// Works like the above example:  
storage.navigate('some folder/some other folder/some file.txt')  
  
// If a file or folder in the navigation chain doesn't exist the entire function returns undefined.  
storage.navigate('an unexistent folder/an unexistent file.txt') // undefined  
  
// If you have files or folders with "/" in the name, you can use an array as input:  
storage.navigate(['some folder', 'a weird folder with / in the name', 'some file.txt'])  
  
// You can call it inside folders too:  
storage.find('some folder').navigate('some other folder/some file.txt')
```

--------------------------------

### Handle authentication events

Source: https://mega.js.org/docs/1.0/tutorial/login

Use event listeners to handle successful login or errors.

```javascript
storage.once('ready', () => {  
  // User is now logged in  
})  
  
storage.once('error', error => {  
  // Some error happened  
})
```

--------------------------------

### Upload Local Folder to MEGA

Source: https://mega.js.org/docs/1.0/examples/folder-uploading

Iterate through a local directory and upload each file to a newly created MEGA folder. This implementation does not support recursive directory uploads.

```javascript
import { getLoggedInStorage } from './logging-in-demo.js'  
const storage = await getLoggedInStorage()  
  
const folderName = prompt('Enter a folder name:')  
const folderStat = await Deno.stat(folderName)  
if (!folderStat.isDirectory) throw Error('Not a directory!')  
  
// First create a folder  
const megaFolder = await storage.mkdir(folderName)  
  
// Then upload files into it  
for await (const entry of Deno.readDir(folderName)) {  
  const filePath = folderName + '/' + entry.name  
  const fileStat = await Deno.stat(filePath)  
  if (fileStat.isDirectory) {  
    throw Error('Recursive folder uploading was not implemented in this demo! Check the other one!')  
  }  
  const data = await Deno.readFile(filePath)  
  await megaFolder.upload(entry.name, data).complete  
}  
  
console.log('The folder was uploaded!', megaFolder)  
```

--------------------------------

### Handle download verification results

Source: https://mega.js.org/docs/1.0/examples/advanced-file-downloader

Logs the status of a downloaded file and renames corrupt files to include a .corrupt extension.

```javascript
      console.log(filePath, 'was been downloaded and verified')  
    } else {  
      // Warn the user if the file is corrupt and rename the file  
      console.log(filePath, 'is corrupt')  
      await Deno.rename(filePath, filePath + '.corrupt')  
    }  
  } else {  
    console.log(filePath, 'was been downloaded')  
  }  
}  
```
Tokens:
Raw