@anyentity/object-store-core

A unified TypeScript interface for object storage across different backends. This library provides a consistent API for storing, retrieving, and managing objects regardless of the underlying storage implementation.

Features

• Unified Interface: Single ObjectStore interface for all storage backends
• Multiple Implementations: Support for file system, in-memory, and runtime-specific storage
• Conditional Exports: Import only the implementations you need
• Type Safety: Full TypeScript support with strict typing
• Metadata Support: Store and retrieve custom metadata with objects
• Stream Support: Handle large objects with streaming APIs

Installation

bun install @anyentity/object-store-core

Usage

Basic Usage

import type { ObjectStore } from "@anyentity/object-store-core";
import { InMemoryObjectStore } from "@anyentity/object-store-core/memory";

const store: ObjectStore = new InMemoryObjectStore();

// Store an object
await store.putObject("my-key", "Hello, World!", {
  contentType: "text/plain",
  metadata: { author: "user123" }
});

// Retrieve an object
const result = await store.getObject("my-key");
console.log(result.body); // "Hello, World!"
console.log(result.metadata); // { author: "user123" }

// List objects
const list = await store.listObjects({ prefix: "my-" });
console.log(list.keys); // ["my-key"]

// Delete an object
await store.deleteObject("my-key");

Available Implementations

InMemoryObjectStore

Fast in-memory storage, perfect for testing and development:

import { InMemoryObjectStore } from "@anyentity/object-store-core/memory";

const store = new InMemoryObjectStore();

BunFileSystemObjectStore (Bun Runtime Only)

File system storage optimized for Bun runtime:

import { BunFileSystemObjectStore } from "@anyentity/object-store-core/bun";

const store = new BunFileSystemObjectStore("./storage");

API Reference

ObjectStore Interface

interface ObjectStore {
  putObject(key: string, body: Buffer | Uint8Array | string | ReadableStream, options?: PutOptions): Promise<void>;
  getObject(key: string): Promise<GetObjectResult>;
  deleteObject(key: string): Promise<void>;
  listObjects(options?: ListOptions): Promise<ListResult>;
}

Types

interface PutOptions {
  contentType?: string;
  metadata?: Record<string, string>;
  acl?: string;
}

interface GetObjectResult {
  body: Buffer | Uint8Array | ReadableStream | string;
  contentType?: string;
  metadata?: Record<string, string>;
}

interface ListOptions {
  prefix?: string;
  maxKeys?: number;
}

interface ListResult {
  keys: string[];
  nextContinuationToken?: string;
  isTruncated: boolean;
}

Development

# Install dependencies
bun install

# Type check
bun run --bun tsc --noEmit

# Run example
bun run index.ts

License

MIT