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

| Local | Filesystem directory | Alien |

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 functions 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