Blob storage reference

npm install @gensx/storage

import { useBlob } from "@gensx/storage";

function useBlob<T = unknown>(
  key: string,
  options?: BlobStorageOptions,
): Blob<T>;

// Simple usage
const blob = useBlob<UserProfile>("users/123.json");
const profile = await blob.getJSON();
 
// With configuration
const blob = useBlob<UserProfile>("users/123.json", {
  kind: "cloud",
  defaultPrefix: "app-data/",
});

// Get JSON data
const data = await blob.getJSON(); // Returns null if not found
 
// Save JSON data
await blob.putJSON(data, options); // Returns { etag: string }

// Get string content
const text = await blob.getString(); // Returns null if not found
 
// Save string content
await blob.putString("Hello world", options); // Returns { etag: string }

// Get binary data with metadata
const result = await blob.getRaw(); // Returns null if not found
// Returns { content, contentType, etag, lastModified, size, metadata }
 
// Save binary data
await blob.putRaw(buffer, options); // Returns { etag: string }

// Get data as a stream
const stream = await blob.getStream();
 
// Save data from a stream
await blob.putStream(readableStream, options); // Returns { etag: string }

// Check if blob exists
const exists = await blob.exists(); // Returns boolean
 
// Delete blob
await blob.delete();
 
// Get metadata
const metadata = await blob.getMetadata(); // Returns null if not found
 
// Update metadata
await blob.updateMetadata({
  key1: "value1",
  key2: "value2",
});

{
  contentType?: string,         // MIME type of the content
  etag?: string,                // For optimistic concurrency control
  metadata?: {                  // Custom metadata key-value pairs
    [key: string]: string
  }
}

import { BlobClient } from "@gensx/storage";

constructor(options?: BlobStorageOptions)

// Default client (uses filesystem locally, cloud in production)
const blobClient = new BlobClient();
 
// Explicitly use filesystem storage
const localClient = new BlobClient({
  kind: "filesystem",
  rootDir: "./my-data",
});
 
// Explicitly use cloud storage with a prefix
const cloudClient = new BlobClient({
  kind: "cloud",
  defaultPrefix: "app-data/",
});

getBlob<T = unknown>(key: string): Blob<T>

const userBlob = blobClient.getBlob<UserProfile>("users/123.json");
const profile = await userBlob.getJSON();
 
// Update the profile
profile.lastLogin = new Date().toISOString();
await userBlob.putJSON(profile);

async listBlobs(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{
  blobs: Array<{ key: string; lastModified: string; size: number }>;
  nextCursor?: string;
}>

const { blobs, nextCursor } = await blobClient.listBlobs({
  prefix: "chats",
});
console.log(
  "Chat histories:",
  blobs.map((blob) => blob.key),
); // ["chats/123.json", "chats/456.json"]

async blobExists(key: string): Promise<boolean>

if (await blobClient.blobExists("settings.json")) {
  console.log("Settings file exists");
} else {
  console.log("Need to create settings file");
}

async deleteBlob(key: string): Promise<DeleteBlobResult>

const { deleted } = await blobClient.deleteBlob("temp/cache.json");
if (deleted) {
  console.log("Cache file was deleted");
}

// Example: Using BlobClient in an Express handler
import express from "express";
import { BlobClient } from "@gensx/storage";
 
const app = express();
const blobClient = new BlobClient();
 
// Save user data endpoint
app.post("/api/users/:userId", async (req, res) => {
  try {
    const { userId } = req.params;
    const userBlob = blobClient.getBlob(`users/${userId}.json`);
 
    // Get existing profile or create new one
    const existingProfile = (await userBlob.getJSON()) || {};
 
    // Merge with updated data
    const updatedProfile = {
      ...existingProfile,
      ...req.body,
      updatedAt: new Date().toISOString(),
    };
 
    // Save the updated profile
    await userBlob.putJSON(updatedProfile);
 
    res.json({ success: true });
  } catch (error) {
    console.error("Error saving user data:", error);
    res.status(500).json({ error: "Failed to save user data" });
  }
});
 
app.listen(3000, () => {
  console.log("Server running on port 3000");
});