API reference

storage creates Layeron bucket and KV storage modules and exposes runtime object operations.

Import

import { storage } from "@layeron/modules"

storage.bucket

Create an R2-backed Layeron Storage bucket.

TypeSpec operation: bucket.

storage.bucket(options: StorageBucketOptions): StorageBucketModule

SecretRef

Reference to a Layeron Secret used by Storage.

Field	Type	Description
kind	”secret_ref”	Secret reference marker.
name	string	Secret name declared in the same app.

StorageEncryptionOptions

Encryption settings for a storage bucket or KV namespace.

Field	Type	Description
mode	StorageEncryptionMode | undefined	Encryption mode. Defaults to managed when a secret is provided.
algorithm	StorageEncryptionAlgorithm | undefined	Encryption algorithm. Defaults to AES-GCM-256.
secret	SecretRef | undefined	Secret used for encryption, decryption, and managed-encryption signed URL tokens.

StorageLifecycleOptions

Lifecycle rules for objects stored in an R2-backed bucket.

Field	Type	Description
deleteAfterDays	int32 | undefined	Delete bucket objects through native Cloudflare R2 lifecycle after this many days.

StorageCommonOptions

Options shared by storage.bucket() and storage.kv().

Field	Type	Description
name	string	Stable storage instance name inside the Layeron app.
namespace	string | undefined	Platform namespace for the instance. Defaults to default.
binding	string | undefined	Custom Cloudflare binding name for the product worker.
shared	StorageSharedResourceOptions | undefined	Reference an existing R2 bucket or KV namespace in the same Cloudflare account.
access	StorageAccessMode | undefined	Default access mode for this storage instance.
metadata	Record<unknown> | undefined	Static metadata recorded on the module declaration.
encryption	StorageEncryptionOptions | undefined	Managed encryption settings for values stored by this instance.
observability	Layeron.Observability.ObservabilityConfig | undefined	Observability settings for storage reads, writes, deletes, listing, and signed URL operations.
placement	Layeron.Common.Placement.LayeronPlacement | undefined	Placement overrides for this storage product instance.

StorageSharedResourceOptions

Existing Cloudflare storage resource used by this Storage module.

Field	Type	Description
resource	string	Stable shared resource name used in Layeron metadata.
bucketName	string | undefined	Existing R2 bucket name. Required for storage.bucket() shared resources.
namespaceId	string | undefined	Existing KV namespace id. Required for storage.kv() shared resources.
prefix	string | undefined	Optional key prefix applied to reads, writes, deletes, lists, and signed URLs.

StorageBucketOptions

Options accepted by storage.bucket() for an R2-backed object bucket.

Field	Type	Description
lifecycle	StorageLifecycleOptions | undefined	Native R2 lifecycle settings for bucket objects.
host	string | undefined	Dedicated hostname for signed URL delivery through the Storage Product Worker.
path	string | undefined	Path prefix for signed URL delivery. Defaults to /__layeron/r2 when host or url is configured.
url	string | undefined	Absolute URL used to infer the signed URL host and path prefix.

StorageKvOptions

Options accepted by storage.kv() for a Cloudflare KV namespace.

Field	Type	Description
ttlSeconds	int32 | undefined	Default KV expiration in seconds for values written by this instance.

StorageBodyOptions

Options accepted by put() when writing a storage value.

Field	Type	Description
contentType	string | undefined	MIME type stored with the value and returned from signed URL reads.
metadata	Record<unknown> | undefined	User metadata stored beside the value.
checksum	string | undefined	Caller-provided checksum stored as public metadata named checksum; callers own checksum validation.
ifNotExists	boolean | undefined	When true, the write succeeds only for a key that is absent. Existing keys fail with storage_key_already_exists and HTTP status 409.
ttlSeconds	int32 | undefined	Per-write KV expiration in seconds.

StorageSignedUrlOptions

Options accepted by bucket.signedUrl().

Field	Type	Description
action	StorageSignedUrlAction | undefined	Operation allowed by the URL. Defaults to read.
expiresInSeconds	int32 | undefined	URL lifetime in seconds. Defaults to 600.
contentType	string | undefined	Required content type for write URLs and response content type for stored values.
metadata	Record<unknown> | undefined	Metadata applied when a write signed URL stores the uploaded object.
maxSizeBytes	int32 | undefined	Maximum upload size accepted by a write signed URL.
oneTime	boolean | undefined	When true, the URL can be consumed once. A replay receives HTTP 410.

StorageSignedUrlResult

Internal result returned by the Storage Product Worker when it creates a signed URL.

Field	Type	Description
url	string	Short-lived URL to send to the client.
expiresAt	string	ISO timestamp when the URL expires.
token	string	Opaque token embedded in the URL.

StoragePutResult

Result returned after storing a value.

Field	Type	Description
key	string	Storage key written by the operation.
size	int32	Original plaintext byte size.
etag	string	Entity tag for the stored value.
contentType	string | undefined	Stored MIME type when provided.
storedAt	string	ISO timestamp when Layeron accepted the write.
keyVersion	string | undefined	Secret version used for managed encryption.
encrypted	boolean | undefined	Whether Layeron encrypted the value before storage.

StorageHeadResult

Metadata returned by head() or attached to a read result.

Field	Type	Description
key	string	Storage key for the value.
size	int32	Original plaintext byte size.
etag	string	Entity tag for the stored value.
contentType	string | undefined	Stored MIME type when present.
metadata	Record<unknown>	User metadata stored beside the value.
storedAt	string	ISO timestamp when the value was stored.
updatedAt	string | undefined	Provider update timestamp when available.
keyVersion	string | undefined	Secret version used for managed encryption.
encrypted	boolean | undefined	Whether Layeron encrypted the value before storage.

StorageReadResult

Read result returned by get().

Field	Type	Description
body	bytes	Value bytes after Layeron-managed decryption when encryption is enabled.

StorageListItem

One item returned by list().

Field	Type	Description
kind	StorageVariant	Storage backend that owns this item.

StorageListOptions

Options accepted by list().

Field	Type	Description
prefix	string | undefined	Only return keys that start with this prefix.
cursor	string | undefined	Provider cursor returned by a previous list call.
limit	int32 | undefined	Maximum number of items to return.

StorageListResult

Result returned by list().

Field	Type	Description
items	StorageListItem[]	Listed storage items.
cursor	string | undefined	Cursor for the next page when more items are available.
truncated	boolean | undefined	Whether the provider stopped before returning every matching item.

StorageDeleteResult

Result returned by delete().

Field	Type	Description
key	string	Storage key targeted by the delete operation.
deleted	boolean	Whether Layeron accepted the delete operation.

StorageModuleConfig

Normalized Storage module configuration recorded in the app spec.

Field	Type	Description
kind	”storage”	Module config kind.
variant	StorageVariant	Storage backend variant.
name	string	Stable storage instance name.
namespace	string	Platform namespace for the instance. Defaults to default.
binding	string	Primary product worker binding name.
access	StorageAccessMode	Default access mode.
metadata	Record<unknown> | undefined	Static metadata recorded on the module declaration.
encryption	StorageEncryptionOptions | undefined	Managed encryption configuration.
lifecycle	StorageLifecycleOptions | undefined	R2 lifecycle settings for bucket instances.
ttlSeconds	int32 | undefined	Default KV expiration in seconds.
signedUrl	StorageSignedUrlEndpointConfig | undefined	Signed URL delivery endpoint for bucket instances.
stateDatabase	StorageStateDatabaseConfig | undefined	Layeron Database-backed state used by one-time signed URLs.
observability	Layeron.Observability.ObservabilityConfig | undefined	Observability settings recorded with the Storage product configuration.
placement	Layeron.Common.Placement.LayeronPlacement | undefined	Placement overrides for this storage product instance.

StorageSignedUrlEndpointConfig

Dedicated endpoint settings for Storage signed URL traffic.

Field	Type	Description
host	string | undefined	Dedicated host used for signed URL delivery.
path	string	Path prefix used for signed URL delivery.

StorageStateDatabaseConfig

Database Product state backing used by Storage for replay-protected signed URLs.

Field	Type	Description
productName	”db”	Product that owns the state database.
namespace	”layeron”	Internal Layeron namespace for product-owned state.
name	string	Database Product instance name.
storeLogicalId	string	Logical id of the state store resource.
migrationLogicalIds	string[]	Migration resource ids applied to the state store.
signedUrlTokenTable	string	Table used to track consumed one-time signed URL tokens.

StorageBucketModule

Layeron bucket module returned by storage.bucket().

Field	Type	Description
name	”storage”	Module name.
config	StorageModuleConfig	Normalized module configuration.
observability	Layeron.Observability.ObservabilityConfig | undefined	Effective observability policy recorded on the module declaration.

StorageKvModule

Layeron KV module returned by storage.kv().

Field	Type	Description
name	”storage”	Module name.
config	StorageModuleConfig	Normalized module configuration.
observability	Layeron.Observability.ObservabilityConfig | undefined	Effective observability policy recorded on the module declaration.

StorageEncryptionMode

Managed encryption behavior for stored values.

Value	Description
none	Store values without Layeron-managed encryption.
managed	Encrypt values in the Storage Product Worker before writing them to Cloudflare storage.

StorageEncryptionAlgorithm

Encryption algorithms supported by Layeron Storage.

Value	Description
aes-gcm-256	AES-GCM with 256-bit key material derived from the configured Secret.

StorageAccessMode

Default object access policy for a storage instance.

Value	Description
private	Objects require application code or a signed URL to read or write.
public	Objects are intended for public delivery when the deployment exposes them.

StorageSignedUrlAction

Action allowed by a generated storage signed URL.

Value	Description
read	Allow downloading or reading an object.
write	Allow uploading or replacing an object.

StorageVariant

Storage backend selected by storage.bucket() or storage.kv().

Value	Description
bucket	Cloudflare R2 object storage for files, assets, and binary payloads.
kv	Cloudflare KV for small read-heavy values and edge configuration data.

Operations

storage.kv

Create a Cloudflare KV-backed Layeron Storage namespace.

TypeSpec operation: kv.

storage.kv(options: StorageKvOptions): StorageKvModule

storagePut

Write bytes to a storage key. ifNotExists writes fail with storage_key_already_exists when the key already exists.

storagePut(key: string, value: bytes, options?: StorageBodyOptions): StoragePutResult

storageGet

Read bytes and metadata from a storage key.

storageGet(key: string): StorageReadResult | null

storageHead

Read metadata for a storage key without returning the body.

storageHead(key: string): StorageHeadResult | null

storageDelete

Delete a storage key.

storageDelete(key: string): StorageDeleteResult

storageList

List keys and metadata in a storage instance.

storageList(options?: StorageListOptions): StorageListResult

storageSignedUrl

Create a short-lived signed URL for a bucket object.

storageSignedUrl(key: string, options?: StorageSignedUrlOptions): string