Skip to main content

Blob Storage Module

Syntropy provides a shared blob storage package for source maps, uploads, and other binary assets:

@eclosion-tech/syntropy-blob-storage

Why this module exists​

  • Keep storage logic consistent across all projects.
  • Switch between S3-compatible providers without app-level rewrites.
  • Support direct-to-storage uploads with presigned URLs.
  • Provide UploadThing-style route validation and typed upload flows.

Install​

npm install @eclosion-tech/syntropy-blob-storage

S3-compatible adapter​

import { S3BlobStorage } from "@eclosion-tech/syntropy-blob-storage";

const storage = new S3BlobStorage({
  bucket: process.env.S3_BUCKET!,
  region: process.env.S3_REGION ?? "us-east-1",
  endpoint: process.env.S3_ENDPOINT, // Optional for R2/MinIO/etc
  forcePathStyle: process.env.S3_FORCE_PATH_STYLE === "true",
  keyPrefix: process.env.S3_KEY_PREFIX, // Optional
  publicBaseUrl: process.env.S3_PUBLIC_BASE_URL, // Optional
});

Direct upload flow​

const signed = await storage.createPresignedUploadUrl({
  key: "uploads/u_123/avatar.png",
  contentType: "image/png",
  expiresInSeconds: 300,
});

Use signed.url with PUT, include signed.headers, then store signed.key in your app database.

UploadThing-style router​

import { BlobUploadService, createUploadRouter } from "@eclosion-tech/syntropy-blob-storage";

const routes = createUploadRouter({
  avatar: {
    accept: ["image/*"],
    maxSizeBytes: 5 * 1024 * 1024,
    buildKey: ({ fileName, input }: { fileName: string; input: { userId: string } }) =>
      `avatars/${input.userId}/${fileName}`,
  },
});

const uploads = new BlobUploadService(storage, routes, {
  keyPrefix: "tenant-assets",
});

BlobUploadService validates file size and MIME type per route, then returns a presigned upload URL.

Methods​

  • put stores binary payloads with metadata.
  • get reads blobs and response metadata.
  • delete removes a blob by key.
  • exists checks if a key exists.
  • list lists keys by optional prefix.
  • createPresignedUploadUrl creates temporary PUT URLs.
  • createPresignedDownloadUrl creates temporary GET URLs.
  • S3_BUCKET
  • S3_REGION
  • S3_ENDPOINT (for non-AWS providers)
  • S3_FORCE_PATH_STYLE
  • S3_KEY_PREFIX
  • S3_PUBLIC_BASE_URL
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_SESSION_TOKEN (optional)

Provider compatibility​

  • AWS S3
  • Cloudflare R2
  • MinIO
  • Any S3-compatible object storage