AIOZ Storage JavaScript SDK Quickstart with client-s3

There's no dedicated AIOZ Storage JavaScript package to install. The AIOZ storage javascript sdk is the standard AWS SDK for JavaScript v3, @aws-sdk/client-s3, pointed at a different endpoint with one extra config flag. This quickstart covers the exact client setup AIOZ's own SDK documentation specifies, then uploading, listing, and downloading objects with it.

TL;DR:

• Install @aws-sdk/client-s3, the same package used against Amazon S3 itself, no AIOZ-specific package exists or is needed.
• AIOZ's own SDK docs specify region: 'us-east-1', a custom endpoint, and forcePathStyle: true as the required client config.
• forcePathStyle is not optional boilerplate, without it the SDK tries virtual-hosted-style URLs that don't resolve against AIOZ Storage's single endpoint.

Is There a Dedicated AIOZ Storage JavaScript SDK?

No, and that's by design, not a gap. AIOZ Storage's S3-compatible API works directly with @aws-sdk/client-s3, the same official AWS SDK package used against Amazon S3. Install it with npm install @aws-sdk/client-s3, there's nothing AIOZ-specific to add on top.

Configuring the S3Client for AIOZ Storage

AIOZ's own SDK documentation specifies this exact configuration:

import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3'

const s3Client = new S3Client({
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY_ID',
    secretAccessKey: 'YOUR_SECRET_ACCESS_KEY'
  },
  endpoint: {
    url: 'https://s3.aiozstorage.network'
  },
  forcePathStyle: true
})

Two settings matter more than the others here. region: 'us-east-1' is required by the SDK's constructor even though AIOZ Storage isn't region-partitioned, the same placeholder-region pattern AIOZ's Python SDK docs use too. And forcePathStyle: true isn't optional: without it, the SDK defaults to virtual-hosted-style requests (bucket.endpoint/key), which don't resolve against AIOZ Storage's single endpoint the way they do against AWS's per-region S3 endpoints. Leave it out and every request fails before it gets anywhere near your bucket.

Uploading an Object

async function uploadFile(bucket, key, body) {
  const command = new PutObjectCommand({
    Bucket: bucket,
    Key: key,
    Body: body,
  })
  return s3Client.send(command)
}

await uploadFile('your-bucket', 'hello.txt', 'Hello from AIOZ Storage')

Every operation in the v3 SDK follows this same command-object pattern: build a Command with the parameters, pass it to s3Client.send(). Body accepts a string, a Buffer, or a readable stream, whatever shape your data is already in, without needing to convert it first.

Listing and Downloading Objects

import { ListObjectsV2Command, GetObjectCommand } from '@aws-sdk/client-s3'

async function listFiles(bucket) {
  const command = new ListObjectsV2Command({ Bucket: bucket })
  const response = await s3Client.send(command)
  return (response.Contents || []).map(obj => obj.Key)
}

async function downloadFile(bucket, key) {
  const command = new GetObjectCommand({ Bucket: bucket, Key: key })
  const response = await s3Client.send(command)
  return response.Body.transformToString()
}

response.Body in the v3 SDK is a web stream, not a plain string, which is why downloadFile calls .transformToString() on it. If you're downloading binary data instead of text, transformToByteArray() does the same job for a Uint8Array instead.

Deleting an Object

import { DeleteObjectCommand } from '@aws-sdk/client-s3'

async function deleteFile(bucket, key) {
  const command = new DeleteObjectCommand({ Bucket: bucket, Key: key })
  return s3Client.send(command)
}

Same pattern as every other operation: build the command, send it. Like the S3 API generally, a delete against a key that doesn't exist still resolves successfully rather than throwing, so this won't tell you whether the file was actually there before you deleted it.

Handling Errors

Every s3Client.send() call can reject, a missing bucket, an expired credential, a network failure, and the v3 SDK throws a typed ServiceException you can catch and inspect:

import { S3ServiceException } from '@aws-sdk/client-s3'

try {
  await s3Client.send(command)
} catch (error) {
  if (error instanceof S3ServiceException) {
    console.error(`S3 error: ${error.name} - ${error.message}`)
  } else {
    throw error
  }
}

error.name gives you the specific error code (NoSuchKey, NoSuchBucket, AccessDenied, and so on), the same information boto3 surfaces through its own exception classes on the Python side of this SDK family.

Frequently Asked Questions

What npm package do I need for the AIOZ Storage JavaScript SDK?
@aws-sdk/client-s3, the standard AWS SDK for JavaScript v3. No separate AIOZ-specific package exists.

Why does the S3Client need forcePathStyle: true for AIOZ Storage?
Without it, the SDK defaults to virtual-hosted-style request URLs (bucket.endpoint/key), which don't work against AIOZ Storage's single endpoint. forcePathStyle switches requests to endpoint/bucket/key instead.

Why does the client need a region if AIOZ Storage isn't region-partitioned?
The SDK's constructor requires a region value regardless of target. AIOZ's own documentation sets it to us-east-1 as a placeholder.

What does response.Body look like when downloading with the v3 SDK?
A web stream, not a plain string or Buffer. Call .transformToString() for text or .transformToByteArray() for binary data.

Does uploading with PutObjectCommand accept a file stream, or only a string?
Both, and a Buffer too. Body accepts whatever shape your data is already in without requiring a conversion step first.

How do I catch and identify S3 errors in the JavaScript SDK?
Catch S3ServiceException, the SDK's base error class for service errors, and check error.name for the specific error code (NoSuchKey, NoSuchBucket, AccessDenied, and similar).

Does deleting a nonexistent key throw an error?
No. Like the S3 API generally, DeleteObjectCommand resolves successfully even if the key was never there, so it won't tell you whether anything was actually deleted.

Is the JavaScript SDK setup different from the Python (boto3) setup?
Same underlying pattern, different syntax: both need a custom endpoint pointed at AIOZ Storage and a path-style addressing flag (forcePathStyle in JS, addressing_style: path in boto3's Config).

Related Reading

• AIOZ Storage Go SDK Quickstart with aws-sdk-go-v2 - the same client setup pattern in Go instead of JavaScript.
• AIOZ Storage CLI Quickstart: AWS CLI with a Custom Endpoint - the same endpoint and credentials, from the command line instead of code.
• Calling AIOZ Storage's S3 API Directly with Postman - the same requests this SDK sends, built and signed by hand.
• File Management API with FastAPI, Boto3, and AIOZ Storage - the same client setup pattern in Python instead of JavaScript.
• Generating Presigned URLs on AIOZ Storage with Python - scoped, temporary upload and download links, the Python side of this same SDK family.
• AIOZ Storage Access Control: Macaroons and Access Grants - generating the credentials this SDK client authenticates with.
• AIOZ Storage Glossary: Bucket, Passphrase, Macaroon - quick definitions for the access grant and endpoint terms used throughout this guide.

References

• AIOZ Storage Documentation: JavaScript SDK
• AWS SDK for JavaScript v3 Documentation: @aws-sdk/client-s3
• AWS SDK for JavaScript v3: Configuring Client Endpoints