From f60d02533ea77fe093d8f3e68ae13eef7409b3b2 Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Fri, 10 Nov 2023 11:49:07 -0700 Subject: [PATCH 1/5] Update JS SDK README --- README.md | 103 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 61 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index fb5ba099..4123398e 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,12 @@ [![NPM](https://nodei.co/npm/minio.png)](https://nodei.co/npm/minio/) -The MinIO JavaScript Client SDK provides simple APIs to access any Amazon S3 compatible object storage server. +The MinIO JavaScript Client SDK provides high level APIs to access any Amazon S3 compatible object storage server. -This quickstart guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) documentation. +This guide will show you how to install the client SDK and execute an example JavaScript program. +For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) documentation. -This document assumes that you have a working [nodejs](http://nodejs.org/) setup in place. +This document presumes you have a working [Node.js](http://nodejs.org/) development environment, version 16 or later. ## Download from NPM @@ -30,15 +31,15 @@ npm install -g ## Initialize MinIO Client -You need five items in order to connect to MinIO object storage server. +The following parameters are needed to connect to a MinIO object storage server: -| Params | Description | -| :-------- | :-------------------------------------------------------------------------------------------------- | -| endPoint | URL to object storage service. | -| port | TCP/IP port number. This input is optional. Default value set to `80` for HTTP and `443` for HTTPs. | -| accessKey | Access key is like user ID that uniquely identifies your account. | -| secretKey | Secret key is the password to your account. | -| useSSL | Set this value to 'true' to enable secure (HTTPS) access | +| Parameter | Description | +| :---------- | :--------------------------------------------------------------------------- | +| `endPoint` | URL for the object storage service. | +| `port` | TCP/IP port number. Optional, defaults to `80` for HTTP and `443` for HTTPs. | +| `accessKey` | Access key (user ID) of an account in the S3 service. | +| `secretKey` | Secret key (password) of an account in the S3 service. | +| `useSSL` | Optional, set to 'true' to enable secure (HTTPS) access. | ```js var Minio = require('minio') @@ -54,9 +55,11 @@ var minioClient = new Minio.Client({ ## Quick Start Example - File Uploader -This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket. +This sample code connects to an object storage server, creates a bucket, and uploads a file to the bucket. +It uses the MinIO `play` server, a public MinIO cluster located at [https://play.min.io](https://play.min.io). -We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public. +The `play` server runs the latest stable version of MinIO and may be used for testing and development. +The access credentials shown in this example are open to the public and all data uploaded to `play` should be considered public and non-protected. #### file-uploader.js @@ -73,24 +76,40 @@ var minioClient = new Minio.Client({ secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG', }) -// File that needs to be uploaded. -var file = '/tmp/photos-europe.tar' +// Destination bucket +var bucket = 'js-test-bucket' -// Make a bucket called europetrip. -minioClient.makeBucket('europetrip', 'us-east-1', function (err) { - if (err) return console.log(err) +// File to upload and name to save as to the bucket +var source_file = '/tmp/test-file.txt' +var destination_file = 'my-test-file.txt' + +// Create the bucket, if it doesn't already exist +minioClient.bucketExists(bucket, function (err, exists) { + if (err) { + return console.log(err) + } + + if (exists) { + console.log('Bucket ' + bucket + ' exists.') + } + else { + minioClient.makeBucket(bucket, 'us-east-1', function (err) { + if (err) return console.log(err) + + console.log('Bucket ' + bucket + ' created successfully in "us-east-1".') + }) +} - console.log('Bucket created successfully in "us-east-1".') var metaData = { 'Content-Type': 'application/octet-stream', 'X-Amz-Meta-Testing': 1234, example: 5678, } - // Using fPutObject API upload your file to the bucket europetrip. - minioClient.fPutObject('europetrip', 'photos-europe.tar', file, metaData, function (err, etag) { + // Using fPutObject API upload your file to the bucket europetrip-test. + minioClient.fPutObject(bucket, destination_file, source_file, metaData, function (err, etag) { if (err) return console.log(err) - console.log('File uploaded successfully.') + console.log('File ' + source_file + ' uploaded successfully as ' + destination_file) }) }) ``` @@ -98,20 +117,20 @@ minioClient.makeBucket('europetrip', 'us-east-1', function (err) { #### Run file-uploader ```sh -node file-uploader.js -Bucket created successfully in "us-east-1". +Bucket js-test-bucket created successfully in "us-east-1". +File /tmp/test-file.txt uploaded successfully as my-test-file.txt -mc ls play/europetrip/ -[2016-05-25 23:49:50 PDT] 17MiB photos-europe.tar +mc ls play/js-test-bucket +[2023-11-10 17:52:20 UTC] 20KiB STANDARD my-test-file.txt ``` ## API Reference -The full API Reference is available here. +The complete API Reference is available here: -- [Complete API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) +- [MinIO JavaScript API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) -### API Reference : Bucket Operations +### Bucket Operations - [`makeBucket`](https://min.io/docs/minio/linux/developers/javascript/API.html#makeBucket) - [`listBuckets`](https://min.io/docs/minio/linux/developers/javascript/API.html#listBuckets) @@ -129,12 +148,12 @@ The full API Reference is available here. - [`getObjectLockConfig`](https://min.io/docs/minio/linux/developers/javascript/API.html#getObjectLockConfig) - [`setObjectLockConfig`](https://min.io/docs/minio/linux/developers/javascript/API.html#setObjectLockConfig) -### API Reference : File Object Operations +### File Object Operations - [`fPutObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#fPutObject) - [`fGetObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#fGetObject) -### API Reference : Object Operations +### Object Operations - [`getObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#getObject) - [`putObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#putObject) @@ -145,27 +164,27 @@ The full API Reference is available here. - [`removeIncompleteUpload`](https://min.io/docs/minio/linux/developers/javascript/API.html#removeIncompleteUpload) - [`selectObjectContent`](https://min.io/docs/minio/linux/developers/javascript/API.html#selectObjectContent) -### API Reference : Presigned Operations +### Presigned Operations - [`presignedGetObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#presignedGetObject) - [`presignedPutObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#presignedPutObject) - [`presignedPostPolicy`](https://min.io/docs/minio/linux/developers/javascript/API.html#presignedPostPolicy) -### API Reference : Bucket Notification Operations +### Bucket Notification Operations - [`getBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#getBucketNotification) - [`setBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#setBucketNotification) - [`removeAllBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#removeAllBucketNotification) - [`listenBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#listenBucketNotification) (MinIO Extension) -### API Reference : Bucket Policy Operations +### Bucket Policy Operations - [`getBucketPolicy`](https://min.io/docs/minio/linux/developers/javascript/API.html#getBucketPolicy) - [`setBucketPolicy`](https://min.io/docs/minio/linux/developers/javascript/API.html#setBucketPolicy) -## Full Examples +## Examples -#### Full Examples : Bucket Operations +#### Bucket Operations - [list-buckets.mjs](https://github.com/minio/minio-js/blob/master/examples/list-buckets.mjs) - [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js) @@ -189,12 +208,12 @@ The full API Reference is available here. - [get-bucket-replication.mjs](https://github.com/minio/minio-js/blob/master/examples/get-bucket-replication.mjs) - [remove-bucket-replication.mjs](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-replication.mjs) -#### Full Examples : File Object Operations +#### File Object Operations - [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js) - [fget-object.js](https://github.com/minio/minio-js/blob/master/examples/fget-object.js) -#### Full Examples : Object Operations +#### Object Operations - [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js) - [get-object.js](https://github.com/minio/minio-js/blob/master/examples/get-object.js) @@ -213,20 +232,20 @@ The full API Reference is available here. - [compose-object.js](https://github.com/minio/minio-js/blob/master/examples/compose-object.js) - [select-object-content.js](https://github.com/minio/minio-js/blob/master/examples/select-object-content.js) -#### Full Examples : Presigned Operations +#### Presigned Operations - [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js) - [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js) - [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js) -#### Full Examples: Bucket Notification Operations +#### Bucket Notification Operations - [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js) - [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js) - [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js) - [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (MinIO Extension) -#### Full Examples: Bucket Policy Operations +#### Bucket Policy Operations - [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js) - [set-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.js) @@ -242,6 +261,6 @@ The full API Reference is available here. ## Contribute -[Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md) +- [Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/minio/minio-js/nodejs.yml) From 002515dc6220c3c3bcd1933be3aaa61d172562a3 Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Wed, 29 Nov 2023 17:34:17 -0700 Subject: [PATCH 2/5] Rework example and other edits (partial) --- README.md | 84 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 49 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 4123398e..fee29ad1 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The MinIO JavaScript Client SDK provides high level APIs to access any Amazon S3 This guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) documentation. -This document presumes you have a working [Node.js](http://nodejs.org/) development environment, version 16 or later. +This document presumes you have a working [Node.js](http://nodejs.org/) development environment, LTS versions v16, v18 or v20. ## Download from NPM @@ -55,20 +55,22 @@ var minioClient = new Minio.Client({ ## Quick Start Example - File Uploader -This sample code connects to an object storage server, creates a bucket, and uploads a file to the bucket. +This sample ECMAScript module connects to an object storage server, creates a bucket, and uploads a file to the bucket. It uses the MinIO `play` server, a public MinIO cluster located at [https://play.min.io](https://play.min.io). The `play` server runs the latest stable version of MinIO and may be used for testing and development. -The access credentials shown in this example are open to the public and all data uploaded to `play` should be considered public and non-protected. +The access credentials shown in this example are open to the public. +All data uploaded to `play` should be considered public and non-protected. -#### file-uploader.js +#### file-uploader.mjs ```js -var Minio = require('minio') +import * as Minio from 'minio' -// Instantiate the minio client with the endpoint -// and access keys as shown below. -var minioClient = new Minio.Client({ +// Instantiate the MinIO client with the endpoint, +// access, and secret keys +// play.min.io is the MinIO public test cluster +const minioClient = new Minio.Client({ endPoint: 'play.min.io', port: 9000, useSSL: true, @@ -76,50 +78,62 @@ var minioClient = new Minio.Client({ secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG', }) +// File to upload +const sourceFile = '/tmp/test-file.txt' + // Destination bucket -var bucket = 'js-test-bucket' +const bucket = 'js-test-bucket' + +// Destination object name +const destinationObject = 'my-test-file.txt' -// File to upload and name to save as to the bucket -var source_file = '/tmp/test-file.txt' -var destination_file = 'my-test-file.txt' -// Create the bucket, if it doesn't already exist +/* How to do this? exists is always undefined +// Create the bucket if it doesn't already exist minioClient.bucketExists(bucket, function (err, exists) { if (err) { - return console.log(err) + console.log(err) + return } +}) +if (exists) { + console.log('Bucket ' + bucket + ' exists.') +} +else { +*/ - if (exists) { - console.log('Bucket ' + bucket + ' exists.') - } - else { - minioClient.makeBucket(bucket, 'us-east-1', function (err) { - if (err) return console.log(err) - console.log('Bucket ' + bucket + ' created successfully in "us-east-1".') - }) +// Create the bucket, default region is us-east-1 +await minioClient.makeBucket(bucket, 'us-east-1') +console.log('Bucket ' + bucket + ' created in "us-east-1".') + +// Set the metadata for the new object +var metaData = { + 'Content-Type': 'text/plain', + 'X-Amz-Meta-Testing': 1234, + example: 5678, } +// fPutObject uploads the file and creates an object in the bucket +// If the object already exists, it is updated with new data +await minioClient.fPutObject(bucket, destinationObject, sourceFile, metaData) +console.log('File ' + sourceFile + + ' uploaded as object ' + destinationObject + + ' to bucket ' + bucket) - var metaData = { - 'Content-Type': 'application/octet-stream', - 'X-Amz-Meta-Testing': 1234, - example: 5678, - } - // Using fPutObject API upload your file to the bucket europetrip-test. - minioClient.fPutObject(bucket, destination_file, source_file, metaData, function (err, etag) { - if (err) return console.log(err) - console.log('File ' + source_file + ' uploaded successfully as ' + destination_file) - }) -}) ``` -#### Run file-uploader +#### Run the File Uploader ```sh +node file-uploader.mjs Bucket js-test-bucket created successfully in "us-east-1". -File /tmp/test-file.txt uploaded successfully as my-test-file.txt +File /tmp/test-file.txt uploaded successfully as my-test-file.txt to bucket js-test-bucket +``` + +Verify the object was created with [`mc`](https://min.io/docs/minio/linux/reference/minio-mc.html): +``` mc ls play/js-test-bucket [2023-11-10 17:52:20 UTC] 20KiB STANDARD my-test-file.txt ``` From cdcf808634c3d5cbf56b04d6ec7afd8b3f2240dc Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Fri, 15 Dec 2023 15:56:13 -0700 Subject: [PATCH 3/5] New version of file upload example --- README.md | 38 ++++++++++++++------------------------ 1 file changed, 14 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index d42a1d78..3b30014d 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ const minioClient = new Minio.Client({ ## Quick Start Example - File Uploader -This sample ECMAScript module connects to an object storage server, creates a bucket, and uploads a file to the bucket. +This example connects to an object storage server, creates a bucket, and uploads a file to the bucket. It uses the MinIO `play` server, a public MinIO cluster located at [https://play.min.io](https://play.min.io). The `play` server runs the latest stable version of MinIO and may be used for testing and development. @@ -67,10 +67,9 @@ All data uploaded to `play` should be considered public and non-protected. ```js import * as Minio from 'minio' -// Instantiate the MinIO client with the endpoint, -// access, and secret keys +// Instantiate the MinIO client with the object store service +// endpoint and an authorized user's credentials // play.min.io is the MinIO public test cluster - const minioClient = new Minio.Client({ endPoint: 'play.min.io', port: 9000, @@ -88,40 +87,31 @@ const bucket = 'js-test-bucket' // Destination object name const destinationObject = 'my-test-file.txt' - -/* How to do this? exists is always undefined -// Create the bucket if it doesn't already exist -minioClient.bucketExists(bucket, function (err, exists) { - if (err) { - console.log(err) - return - } -}) +// Check if the bucket exists +// If it doesn't, create it +const exists = await minioClient.bucketExists(bucket) if (exists) { console.log('Bucket ' + bucket + ' exists.') } else { -*/ - - -// Create the bucket, default region is us-east-1 -await minioClient.makeBucket(bucket, 'us-east-1') -console.log('Bucket ' + bucket + ' created in "us-east-1".') + await minioClient.makeBucket(bucket, 'us-east-1') + console.log('Bucket ' + bucket + ' created in "us-east-1".') +} -// Set the metadata for the new object +// Set the object metadata var metaData = { 'Content-Type': 'text/plain', 'X-Amz-Meta-Testing': 1234, example: 5678, } -// fPutObject uploads the file and creates an object in the bucket -// If the object already exists, it is updated with new data +// Upload the file with fPutObject +// If an object with the same name exists, +// it is updated with new data await minioClient.fPutObject(bucket, destinationObject, sourceFile, metaData) console.log('File ' + sourceFile + ' uploaded as object ' + destinationObject + - ' to bucket ' + bucket) - + ' in bucket ' + bucket) ``` #### Run the File Uploader From fa76b220f1cf55aee47415562fc0243cd884b77b Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Mon, 18 Dec 2023 11:12:15 -0700 Subject: [PATCH 4/5] npm run format --- README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3b30014d..bb5324f0 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The MinIO JavaScript Client SDK provides high level APIs to access any Amazon S3 compatible object storage server. -This guide will show you how to install the client SDK and execute an example JavaScript program. +This guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) documentation. This document presumes you have a working [Node.js](http://nodejs.org/) development environment, LTS versions v16, v18 or v20. @@ -92,8 +92,7 @@ const destinationObject = 'my-test-file.txt' const exists = await minioClient.bucketExists(bucket) if (exists) { console.log('Bucket ' + bucket + ' exists.') -} -else { +} else { await minioClient.makeBucket(bucket, 'us-east-1') console.log('Bucket ' + bucket + ' created in "us-east-1".') } @@ -109,9 +108,7 @@ var metaData = { // If an object with the same name exists, // it is updated with new data await minioClient.fPutObject(bucket, destinationObject, sourceFile, metaData) -console.log('File ' + sourceFile + - ' uploaded as object ' + destinationObject + - ' in bucket ' + bucket) +console.log('File ' + sourceFile + ' uploaded as object ' + destinationObject + ' in bucket ' + bucket) ``` #### Run the File Uploader From 4c0c2b736a0995963bc33001d884cc2f207cb767 Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Mon, 18 Dec 2023 11:22:53 -0700 Subject: [PATCH 5/5] Correct endPoint arg desc --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bb5324f0..a21d0fc4 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ The following parameters are needed to connect to a MinIO object storage server: | Parameter | Description | | :---------- | :--------------------------------------------------------------------------- | -| `endPoint` | URL for the object storage service. | +| `endPoint` | Hostname of the object storage service. | | `port` | TCP/IP port number. Optional, defaults to `80` for HTTP and `443` for HTTPs. | | `accessKey` | Access key (user ID) of an account in the S3 service. | | `secretKey` | Secret key (password) of an account in the S3 service. |