Skip to main content

Buckets API

Buckets organize and namespace objects in Lioran S3. Bucket operations can be performed via the global client.buckets manager or through a scoped client.bucket(name) handle.

1. Create a Bucket​

Create a bucket using client.buckets.create():

import { BastionClient } from "@liorans3/driver";

const client = new BastionClient("bastion://admin:YOUR_PASSWORD@127.0.0.1:27118");

// Create bucket with 50 GiB quota and versioning disabled
const bucket = await client.buckets.create("user-uploads", {
  quotaBytes: 50 * 1024 * 1024 * 1024, // 50 GiB
  versioning: false,
});

console.log(`Created bucket '${bucket.name}' (Owner: ${bucket.owner})`);

Options (CreateBucketOptions)​

FieldTypeDescription
quotaBytesnumberOptional maximum storage quota in bytes.
versioning / versioningEnabledbooleanEnable object versioning for this bucket (default: false).
signalAbortSignalOptional abort signal to cancel the request.

2. List Buckets​

List all buckets accessible to the authenticated account:

const buckets = await client.buckets.list();

for (const b of buckets) {
  console.log(`- ${b.name} (Quota: ${b.quota_bytes ?? "Unlimited"}, Versioning: ${b.versioning_enabled})`);
}

Return Type (BucketMetadata)​

interface BucketMetadata {
  name: string;
  owner: string;
  quota_bytes: number | null;
  versioning_enabled: boolean;
  tags?: Record<string, string>;
  created_at?: string;
  updated_at?: string;
}

3. Get Bucket Metadata​

Fetch detailed configuration and metadata for a specific bucket:

const meta = await client.buckets.get("user-uploads");

// Or using scoped BucketHandle:
const handle = client.bucket("user-uploads");
const info = await handle.info();

console.log("Bucket Owner:", info.owner);
console.log("Created At:", info.created_at);
console.log("Quota Bytes:", info.quota_bytes);

4. Update Bucket Configuration​

Partially update bucket parameters such as quotas, versioning state, and metadata tags:

const updated = await client.buckets.update("user-uploads", {
  quotaBytes: 100 * 1024 * 1024 * 1024, // Increase quota to 100 GiB
  versioning: true,                     // Enable versioning
  tags: {
    environment: "production",
    team: "media-platform",
  },
});

console.log("Updated Bucket Tags:", updated.tags);

5. Delete a Bucket​

Delete a bucket from the server:

// Standard deletion (fails if bucket contains objects)
await client.buckets.delete("temp-bucket");

// Force deletion (recursively deletes all objects and bucket)
await client.buckets.delete("temp-bucket", { force: true });

// Or via scoped BucketHandle:
await client.bucket("temp-bucket").deleteBucket(true);

:::warning Force Deletion Setting force: true permanently deletes all committed objects and metadata associated with the bucket. This operation cannot be undone. :::