Skip to content

Commit

Permalink
Remove observable interface
Browse files Browse the repository at this point in the history
  • Loading branch information
@clostao
clostao authored Dec 23, 2024
2 parents 737fa13 + 588d1ac commit 3a03320
Show file tree
Hide file tree
Showing 8 changed files with 202 additions and 258 deletions.
126 changes: 42 additions & 84 deletions packages/auto-drive/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,43 +25,40 @@ yarn add @autonomys/auto-drive
Here is an example of how to use the `uploadFileFromFilepath` method to upload a file with optional encryption and compression:

```typescript
import { uploadFileFromFilepath } from '@autonomys/auto-drive'
import { uploadFileFromFilepath,createAutoDriveApi } from '@autonomys/auto-drive'

const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
const filePath = 'path/to/your/file.txt' // Specify the path to your file
const options = {
password: 'your-encryption-password', // Optional: specify a password for encryption
compression: true,
// an optional callback useful for large file uploads
onProgress?: (progress: number) => {
console.log(`The upload is completed is ${progress}% completed`)
}
}

const uploadObservable = uploadFileFromFilepath(api, filePath, options)
.then(() => {
console.log('File uploaded successfully!')
})
.catch((error) => {
console.error('Error uploading file:', error)
})
const cid = await uploadFileFromFilepath(api, filePath, options)

console.log(`The file is uploaded and its cid is ${cid}`)
```

### How to upload [File](https://developer.mozilla.org/en-US/docs/Web/API/File) interface

```typescript
import { uploadFileFromFilepath } from '@autonomys/auto-drive'
import { uploadFileFromInput, createAutoDriveApi } from '@autonomys/auto-drive'

const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
const filePath = 'path/to/your/file.txt' // Specify the path to your file

// e.g Get File from object from HTML event
const file: File = e.target.value // Substitute with your file
const options = {
password: 'your-encryption-password', // Optional: specify a password for encryption
compression: true,
}
const cid = await uploadFileFromInput(api, file, options)

const uploadObservable = uploadFile(api, filePath, options)
.then(() => {
console.log('File uploaded successfully!')
})
.catch((error) => {
console.error('Error uploading file:', error)
})
console.log(`The file is uploaded and its cid is ${cid}`)
```

### How to upload a file from a custom interface?
Expand All @@ -83,7 +80,7 @@ For more info about asynn generator visit [this website](https://developer.mozil
You could upload any file that could be represented in that way. For example, uploading a file as a `Buffer`

```typescript
import { uploadFile } from '@autonomys/auto-drive'
import { createAutoDriveApi, uploadFile } from '@autonomys/auto-drive'

const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
const buffer = Buffer.from(...);
Expand All @@ -100,96 +97,53 @@ const genericFile = {
const options = {
password: 'your-encryption-password', // Optional: specify a password for encryption
compression: true,
// an optional callback useful for large file uploads
onProgress?: (progress: number) => {
console.log(`The upload is completed is ${progress}% completed`)
}
}

const uploadObservable = uploadFile(api, genericFile, options)
.then(() => {
console.log('File uploaded successfully!')
})
.catch((error) => {
console.error('Error uploading file:', error)
})
const cid = uploadFile(api, genericFile, options)

console.log(`The file is uploaded and its cid is ${cid}`)
```

### How to upload a folder from folder? (Not available in browser)

```ts
import { uploadFolderFromFolderPath } from '@autonomys/auto-drive'
import { createAutoDriveApi, uploadFolderFromFolderPath } from '@autonomys/auto-drive'

const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
const folderPath = 'path/to/your/folder' // Specify the path to your folder

const options = {
uploadChunkSize: 1024 * 1024, // Optional: specify the chunk size for uploads
password: 'your-encryption-password', // Optional: If folder is encrypted
// an optional callback useful for large file uploads
onProgress: (progress: number) => {
console.log(`The upload is completed is ${progress}% completed`)
},
}

const uploadObservable = uploadFolderFromFolderPath(api, folderPath, options)
```

**Note: If a folder is tried to be encrypted a zip file would be generated and that file would be encrypted and uploaded.**

### Handle observables

Since uploads may take some time, specially in big-sized files. Uploads do implement `rxjs` observables so you could have feedback about the process or even show your users the progress of the upload.

For that reason when file upload functions return `PromisedObservable<UploadFileStatus>`:

```typescript
export type UploadFileStatus = {
type: 'file'
progress: number
cid?: CID
}
```
Being the cid only returned (and thus optional) when the upload is completed.
Similarly, for folder uploads the functions return `PromisedObservable<UploadFolderStatus>`
```ts
export type UploadFolderStatus = {
type: 'folder'
progress: number
cid?: CID
}
```
**e.g Show upload progress in React**
```typescript
const [progress, setProgress] = useState<number>(0)
const folderCID = await uploadFolderFromFolderPath(api, folderPath, options)

useEffect(async () => {
const finalStatus = await uploadFileFromInput(api, genericFile, options).forEach((status) => {
setProgress(status.progress)
})
})
console.log(`The folder is uploaded and its cid is ${folderCID}`)
```

**e.g Ignore observables**

Other users may want to not use the progress observability. For having a promise instead the field `promise` is a Promise that resolves into `UploadFileStatus` and `UploadFolderStatus` for files and folders respectively.

e.g

```ts
const status = await uploadFileFromInput(api, genericFile, options).promise
const cid = status.cid
```
**Note: If a folder is tried to be encrypted a zip file would be generated and that file would be encrypted and uploaded.**

### Example Usage of Download

Here is an example of how to use the `downloadFile` method to download a file from the server:

```typescript
import { downloadObject } from '@autonomys/auto-drive'
import { createAutoDriveApi, downloadFile } from '@autonomys/auto-drive'

const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key

try {
const cid = '..'
const stream = await downloadObject(api, { cid })
const stream = await downloadFile(api, cid)
let file = Buffer.alloc(0)
for await (const chunk of stream) {
file = Buffer.concat([file, chunk])
Expand All @@ -205,16 +159,20 @@ try {
Here is an example of how to use the `getRoots` method to retrieve the root directories:

```typescript
import { createAutoDriveApi, downloadObject } from '@autonomys/auto-drive'
import fs from 'fs'
import { createAutoDriveApi, apiCalls, Scope } from '@autonomys/auto-drive'

const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key

try {
const stream = fs.createWriteStream('/path/to/file')
const asyncBuffer = await downloadObject(api, { cid })
for await (const buffer of asyncBuffer) {
stream.write(buffer)
const myFiles = await apiCalls.getRoots(api, {
scope: Scope.User,
limit: 100,
offset: 0,
})

console.log(`Retrieved ${myFiles.rows.length} files of ${myFiles.totalCount} total`)
for (const file of myFiles.rows) {
console.log(`${file.name} - ${file.headCid}: ${file.size}`)
}
} catch (error) {
console.error('Error downloading file:', error)
Expand Down
1 change: 0 additions & 1 deletion packages/auto-drive/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@
"jszip": "^3.10.1",
"mime-types": "^2.1.35",
"process": "^0.11.10",
"rxjs": "^7.8.1",
"stream": "^0.0.3",
"zod": "^3.23.8"
},
Expand Down
Loading

0 comments on commit 3a03320

Please sign in to comment.