Behavior & Limits
Guarantees, limits, and platform-specific behavior for Alien KV.
Guarantees
On cloud platforms (AWS, GCP, Azure), Alien provisions and manages the KV backing service. These guarantees apply:
Strong Single-Key Consistency. A get() after a successful set() on the same key returns the new value immediately. Firestore is always strongly consistent, DynamoDB uses strongly consistent reads, and Table Storage is strongly consistent within a region.
Atomic Conditional Create. set() with ifNotExists: true is atomic across all platforms. If two concurrent callers try to create the same key, exactly one succeeds and the other fails. Safe for distributed locks and idempotency checks.
Durability. Data is replicated across multiple availability zones by the cloud provider.
TTL is a Soft Hint. When you set a TTL, the key becomes invisible on read after expiry — get() returns undefined and exists() returns false. Physical deletion of the underlying data is eventual and varies by platform (see below). Do not rely on storage being reclaimed at a specific time.
Delete Idempotency. Deleting a non-existent key succeeds silently.
Limits
These are enforced by Alien on all platforms:
| Limit | Value |
|---|---|
| Max key size | 512 bytes |
| Key charset | a-z A-Z 0-9 - _ : . |
| Max value size | 24 KiB (24,576 bytes) |
Scan Semantics
Scan operations have intentionally weak guarantees to remain portable:
- Unordered. Results may arrive in any order.
- May contain duplicates. Your application must deduplicate.
- Cursors are ephemeral. Do not persist or share cursors.
- Not a snapshot. Concurrent writes may or may not appear in results.
Platform Details
AWS (DynamoDB)
- On-demand billing (pay-per-request). No capacity planning needed.
- 16 hash buckets for load distribution (transparent to your code).
- TTL: physical deletion within ~48 hours of expiry.
- Per-partition throughput: 3,000 RCU + 1,000 WCU/second.
GCP (Firestore)
- Always strongly consistent. Only the default database is used.
- TTL: physical deletion within ~24 hours of expiry.
- Ramp-up required: starts at ~500 writes/sec, increases 50% every 5 minutes.
Azure (Table Storage)
- 16 partition buckets for load distribution.
- No native TTL. Alien filters expired items on read, but they are never physically deleted.
- Per-partition throughput: 2,000 entities/second.
Local
- Backed by sled (embedded database). Data persists across restarts.
- Writes are flushed to disk synchronously (crash-safe).
- TTL: exact lazy deletion — expired items removed when accessed.
- Scan returns sorted results. This is a sled implementation detail — do not rely on ordering in production code.
Design Decisions
512-byte key limit. DynamoDB supports 2,048-byte keys, but Azure Table Storage is more constrained. Alien enforces 512 bytes for portability.
24 KiB value limit. DynamoDB allows 400 KB, Firestore 1 MiB. Alien enforces 24 KiB to encourage small, fast lookups and Storage for larger objects.
Restricted key charset. Azure Table Storage disallows many special characters. Alien restricts the charset globally so keys are valid on every platform.