Quick start ​

Sobj gives your application a single, clean interface for working with object storage. Because the storage engine is decoupled behind an adapter, you can experiment locally with zero configuration.

In this quick start, we will set up an in-memory client to run storage operations.

🛠️ 1. Create the Client ​

For local testing, we use the @sobj/memory adapter. Import sobj and the memory adapter, then initialize the client:

import { sobj } from 'sobj'
import { memory } from '@sobj/memory'

const storage = sobj(memory())

The storage client is now ready to receive operations. If you decide to switch to a production provider later (such as S3, R2, B2, or MinIO), you will only replace the memory() call with your cloud provider's adapter — the rest of your application code remains unchanged.

📥 2. Store an Object (put) ​

Store some data by providing a unique key and its content:

await storage.put('docs/hello.txt', 'Hello, Sobj!')

The body parameter accepts a string, Uint8Array, ArrayBuffer, Blob, or a ReadableStream.

📤 3. Retrieve an Object (get) ​

Fetch the object back using its key:

const object = await storage.get('docs/hello.txt')

// Read the body as a stream
const response = new Response(object.body)
const text = await response.text()

console.log(text) // "Hello, Sobj!"
console.log(object.metadata.size) // byte size of the object

Note: If an object does not exist, get returns null instead of raising an exception. This reduces try/catch blocks in your business logic.

🔍 4. Get Object Metadata (head) ​

If you only need information about an object (like its size or content type) without downloading the content body, use head:

const metadata = await storage.head('docs/hello.txt')

console.log(`Content type: ${metadata.contentType}`)
console.log(`Last modified: ${metadata.lastModified}`)

📋 5. List Stored Objects (list) ​

List all keys matching a specific prefix in the storage:

const result = await storage.list({ prefix: 'docs/' })

for (const item of result.objects) {
  console.log(`- ${item.key} (${item.size} bytes)`)
}

🗑️ 6. Delete an Object (delete) ​

Remove the files when they are no longer needed:

await storage.delete('docs/hello.txt')

🗺️ Next Steps ​

Now that you are familiar with the basic CRUD operations, explore how to build a custom storage solution or swap to cloud backends:

• Custom Adapters — Write a custom storage provider in a few lines.
• Adapters Catalogs — Find officially supported storage adapters.
• API Reference — Explore full signatures of Sobj operations.