API Reference

Get a handle with storage(name) from @alienplatform/sdk (TypeScript) or alien_bindings::Bindings::from_env()?.storage(name).await? (Rust). Constructing the TypeScript handle does no I/O — the resource is resolved on the first operation.

get

Retrieves an object by path.

const { data, meta, attributes } = await storage.get(path)
const json = JSON.parse(data.toString("utf8"))   // data: Buffer

console.log(meta.size, meta.eTag)                // ObjectMeta
console.log(attributes.contentType)              // StorageObjectAttributes

Returns: StorageGetResult — { data, meta, attributes }. data is the object bytes (Buffer), meta is the object's ObjectMeta, and attributes are its stored StorageObjectAttributes (content type, cache control, custom metadata, …).

Errors:

• Object not found — throws with a not-found error.
• STORAGE_OPERATION_FAILED — backend error (retryable).

put

Stores an object. Overwrites if the path already exists.

// data: Buffer | Uint8Array — encode strings/JSON yourself
const { eTag, version } = await storage.put(
  "config.json",
  Buffer.from(JSON.stringify(config)),
)

// Store object attributes alongside the bytes
await storage.put("reports/q1.pdf", pdfBytes, {
  attributes: {
    contentType: "application/pdf",
    contentDisposition: 'attachment; filename="q1.pdf"',
    cacheControl: "public, max-age=3600",
    metadata: { quarter: "q1", schema: "report-v1" },
  },
})

Returns: StoragePutResult — { eTag?, version? }, the provider identifiers for the written object when the backend reports them.

Attribute-bearing writes are rejected before any payload is written on backends that can't persist them: the local filesystem backend rejects all attributes, and GCS rejects contentEncoding: "gzip" (its decompressive transcoding breaks byte-exact reads; other encodings like br work). See Behavior & Limits.

delete

Deletes an object. Deleting a non-existent object is a no-op.

await storage.delete(path)

storage.delete(&path.into()).await?;

list

Lists objects under a prefix.

// Resolves to an array of object metadata
const objects = await storage.list("reports/")
for (const obj of objects) {
  console.log(obj.location, obj.size, obj.lastModified)
}

// List everything
const all = await storage.list()

Returns: ObjectMeta[] in TypeScript — { location, size, lastModified, eTag?, version? }. Rust streams ObjectMeta and also offers list_with_delimiter for directory-style browsing.

list() is metadata-only — cloud list APIs don't return object attributes. Use head to read a specific object's attributes.

head

Returns object metadata and attributes without downloading the object body.

const { meta, attributes } = await storage.head(path)
console.log(meta.size, meta.eTag, attributes.contentType)

let meta = storage.head(&path.into()).await?;

Returns: StorageHeadResult — { meta, attributes }, the same ObjectMeta and StorageObjectAttributes as get, without the payload.

Errors: throws if the object does not exist.

copy

Copies an object from one path to another within the same storage resource.

await storage.copy(from, to)

storage.copy(&from.into(), &to.into()).await?;

// Rust also exposes rename and conditional variants
storage.rename(&from.into(), &to.into()).await?;
storage.copy_if_not_exists(&from.into(), &to.into()).await?;

signedUrl

Generates a time-limited presigned request for direct client access. The result is a full request description — URL plus the method and headers to replay it with — so it works on every provider, including local stores.

const req = await storage.signedUrl({
  method: "GET",          // "GET" | "PUT" | "DELETE"
  path: "reports/q1.json",
  expiresIn: 3600,        // seconds
})
// req: { url, method, headers }

Returns: PresignedRequest — { url: string, method: string, headers: Record<string, string> }

In Rust, use presigned_get, presigned_put, and presigned_delete:

let request = storage.presigned_get(&path.into(), Duration::from_secs(3600)).await?;

Advanced operations (Rust)

The Rust Storage handle also implements the object_store ObjectStore trait, which adds range reads, conditional writes, streaming lists, delimiter listing, and rename:

// Range read
let chunk = storage.get_range(&path.into(), 0..1024).await?;

// Conditional write — only if the path doesn't already exist
storage.put_opts(&path.into(), payload, PutOptions {
    mode: PutMode::Create,
    ..Default::default()
}).await?;

// Directory-style listing
let result = storage.list_with_delimiter(Some(&"reports/".into())).await?;

// Move an object (copy + delete)
storage.rename(&from.into(), &to.into()).await?;

The Rust handle also exposes conditional copy_if_not_exists / rename_if_not_exists and the binding introspection helpers get_base_dir() / get_url(). The TypeScript handle is deliberately minimal; use these from Rust, or use a native cloud SDK for provider-specific features.

Types

ObjectMeta

interface ObjectMeta {
  location: string        // Object path within the store
  size: number            // Object size in bytes
  lastModified: string    // Last-modified timestamp (RFC 3339)
  eTag?: string           // Provider entity tag, when available
  version?: string        // Provider object version, when available
}

StorageObjectAttributes

Provider-neutral attributes returned with a stored object by get and head.

interface StorageObjectAttributes {
  contentType?: string          // Stored MIME type
  contentDisposition?: string   // Stored browser content-disposition behavior
  contentEncoding?: string      // Stored content encoding
  contentLanguage?: string      // Stored content language
  cacheControl?: string         // Stored cache-control policy
  storageClass?: string         // Provider storage class, when reported
  metadata: Record<string, string>  // User-defined object metadata
}

StoragePutAttributes

Attributes accepted by put under options.attributes — the writable subset of StorageObjectAttributes (storageClass is read-only).

interface StoragePutAttributes {
  contentType?: string
  contentDisposition?: string
  contentEncoding?: string      // GCS rejects "gzip"
  contentLanguage?: string
  cacheControl?: string
  metadata?: Record<string, string>
}

StorageGetResult / StorageHeadResult / StoragePutResult

interface StorageGetResult {
  data: Buffer
  meta: ObjectMeta
  attributes: StorageObjectAttributes
}

interface StorageHeadResult {
  meta: ObjectMeta
  attributes: StorageObjectAttributes
}

interface StoragePutResult {
  eTag?: string
  version?: string
}

PresignedRequest

interface PresignedRequest {
  url: string                       // The presigned URL
  method: string                    // HTTP method to replay it with
  headers: Record<string, string>   // Headers to include
}