Overview

Storage lets you store and retrieve files, blobs, and objects of any size — from small JSON documents to multi-gigabyte datasets. Objects are organized by key (path) and accessed via a simple put/get/list/delete API.

Platform Mapping

Platform	Backing Service	Provisioned by
AWS	Amazon S3	Alien
GCP	Google Cloud Storage	Alien
Azure	Azure Blob Storage	Alien
Kubernetes / On-Prem	External (S3, MinIO, GCS, etc.)	Cluster operator
Local	Filesystem directory	Alien

On Kubernetes / on-prem, Storage is not provisioned by Alien. The cluster operator provides the external storage service and configures it via Helm values.

When to Use

Use Storage for files, blobs, and large objects — uploads, reports, generated artifacts, backups, static assets. Objects can be any size up to 5 TB.

Don't use Storage as a database. For key-based lookups with TTL and atomic operations, use KV.

Stack Definition

Declare a Storage resource in your alien.ts:

const data = new alien.Storage("data")
  .publicRead(false)
  .versioning(false)
  .lifecycleRules([{ days: 90 }])
  .build()

Method	Type	Default	Description
`id` (constructor)	`string`	required	Resource identifier. Dot-separated labels, each ≤ 63 chars.
`.publicRead(value)`	`boolean`	`false`	Allow public read access without authentication.
`.versioning(value)`	`boolean`	`false`	Enable object versioning. Not supported on Azure.
`.lifecycleRules(rules)`	`LifecycleRule[]`	`[]`	Auto-delete objects after `days`. Optional `prefix` filter. Not supported on Azure.

Quick Start

Use it in your application:

import { storage } from "@alienplatform/sdk"

const data = await storage("data")

await data.put("reports/q1.json", JSON.stringify(report))
const result = await data.get("reports/q1.json")

let ctx = AlienContext::from_env().await?;
let data = ctx.bindings().load_storage("data").await?;

data.put(&"reports/q1.json".into(), bytes).await?;
let obj = data.get(&"reports/q1.json".into()).await?;

Core Operations

Store an Object

// String or JSON
await data.put("config.json", JSON.stringify({ version: 2 }))

// Binary data
await data.put("image.png", imageBytes, { contentType: "image/png" })

// Conditional write — only if the key doesn't already exist
await data.put("lock.json", "{}", { ifNotExists: true })

// Bytes
data.put(&"config.json".into(), bytes).await?;

// Conditional write (Create mode)
data.put_opts(&"lock.json".into(), payload, PutOptions {
    mode: PutMode::Create,
    ..Default::default()
}).await?;

Retrieve an Object

const result = await data.get("reports/q1.json")  // { meta, data: Uint8Array }
const text = await data.getText("reports/q1.json") // string
const json = await data.getJson("reports/q1.json") // parsed JSON

// Partial read (range)
const chunk = await data.get("large-file.bin", { rangeStart: 0, rangeEnd: 1023 })

let result = data.get(&"reports/q1.json".into()).await?;
let bytes = result.bytes().await?;

// Range read
let range_bytes = data.get_range(&"large-file.bin".into(), 0..1024).await?;

List Objects

// Iterate all objects under a prefix
for await (const obj of data.list("reports/")) {
  console.log(obj.location, obj.size)
}

// Directory-style listing
const result = await data.listWithDelimiter("reports/")
console.log(result.commonPrefixes) // ["reports/2024/", "reports/2025/"]
console.log(result.objects)        // objects directly under "reports/"

Delete, Copy, Rename

await data.delete("reports/old.json")           // no-op if not found
await data.copy("reports/q1.json", "archive/q1.json")
await data.rename("temp/draft.json", "reports/final.json")

Signed URLs

Generate time-limited URLs for direct client access:

const { url } = await data.signedUrl("reports/q1.json", {
  operation: "get",
  expiresInSeconds: 3600,
})

Triggers

Storage events can trigger workers when objects are created or deleted:

import { onStorageEvent } from "@alienplatform/sdk"

onStorageEvent("data", async (event) => {
  console.log(event.type, event.key)  // "created", "reports/q1.json"
}, { prefix: "reports/" })

See Behavior & Limits for trigger support per platform.

On this page