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 = storage("data")

await data.put("reports/q1.json", Buffer.from(JSON.stringify(report)))
const { data: bytes } = await data.get("reports/q1.json")

Core Operations

Store an Object

// put() takes bytes — encode strings/JSON yourself
await data.put("config.json", Buffer.from(JSON.stringify({ version: 2 })))

// Binary data, with object attributes and custom metadata
await data.put("image.png", imageBytes, {
  attributes: {
    contentType: "image/png",
    cacheControl: "public, max-age=86400",
    metadata: { source: "avatar-upload" },
  },
})

Retrieve an Object

const object = await data.get("reports/q1.json")
const json = JSON.parse(object.data.toString("utf8"))   // data: Buffer
console.log(object.meta.eTag, object.attributes.contentType)

// Metadata and attributes without the body
const { meta, attributes } = await data.head("reports/q1.json")

List Objects

// list() resolves to an array of object metadata
for (const obj of await data.list("reports/")) {
  console.log(obj.location, obj.size)
}

Delete and Copy

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

Presigned Requests

Generate time-limited presigned requests for direct client access:

const req = await data.signedUrl({
  method: "GET",
  path: "reports/q1.json",
  expiresIn: 3600,
})
// req: { url, method, headers } — replay it from the client

Triggers

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

import { onStorageEvent } from "@alienplatform/sdk"

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

See Behavior & Limits for trigger support per platform.

On this page