Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove observable interface #210

Merged
merged 4 commits into from
Dec 23, 2024
Merged

Remove observable interface #210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cae1ce6
update: remove observable interface
clostao Dec 20, 2024
2d3e98b
chore: update lock
clostao Dec 20, 2024
d3d6fb6
update: substitute observable handling for promise based
clostao Dec 23, 2024
588d1ac
update: fix not fully plug&play examples
clostao Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 42 additions & 84 deletions packages/auto-drive/README.md
View file
Open in desktop
marc-aurele-besner marked this conversation as resolved.
Show resolved Hide resolved
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
Open in desktop
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
Loading