Skip to content
Browse documentation
typescript sdk

Store and retrieve files

Persist an immutable blob and validate its bytes against a retained descriptor.

Create a bounded object

Give each object an application-owned ID. Set the maximum byte count once and retain the returned descriptor with its owner.

import { createBlobStorage } from "@smoothie-framework/storage";
import { createFilesystemBlobAdapter } from "@smoothie-framework/storage-filesystem";

const storage = createBlobStorage(
  await createFilesystemBlobAdapter(".data/blobs"),
  1024 * 1024,
);
const descriptor = await storage.create(
  crypto.randomUUID(),
  new TextEncoder().encode("A private document"),
);
const bytes = await storage.read(descriptor);
// Delete only after checking application permissions and live references.
await storage.delete(descriptor.id);

Handle conflicts and uncertain writes

Creation does not overwrite an existing key. Reads check descriptor size and digest. Input bytes are copied before publication; do not treat a descriptor's ID as authorization.

An ambiguous remote failure may still have created the object. Do not race cleanup against an active create or retry by overwriting it. Coordinate recovery through application records.

For streaming uploads, readBoundedBlobStream helps enforce byte limits before allocation. Still enforce the host's request-size limits before buffering untrusted input.