@casfa/storage-s3 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casfa/storage-s3",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "S3 storage provider for CAS",
   "type": "module",
   "main": "./dist/index.js",

package/README.md

@@ -1,182 +0,0 @@
-# @casfa/storage-s3
-
-S3 storage provider for CAS.
-
-## Installation
-
-```bash
-bun add @casfa/storage-s3
-```
-
-## Overview
-
-An S3-backed storage provider for CAS (Content-Addressable Storage). Suitable for cloud deployments with high availability and durability requirements.
-
-## Usage
-
-### Basic Usage
-
-```typescript
-import { createS3Storage } from '@casfa/storage-s3';
-
-const storage = createS3Storage({
-  bucket: 'my-cas-bucket',
-  region: 'us-east-1',
-  prefix: 'cas/',  // Optional key prefix
-});
-
-// Store data
-await storage.put('node:abcd1234...', data);
-
-// Retrieve data
-const data = await storage.get('node:abcd1234...');
-
-// Check existence
-const exists = await storage.has('node:abcd1234...');
-
-// Delete
-const deleted = await storage.delete('node:abcd1234...');
-```
-
-### With LRU Cache
-
-```typescript
-import { createS3StorageWithCache } from '@casfa/storage-s3';
-
-const storage = createS3StorageWithCache({
-  bucket: 'my-cas-bucket',
-  region: 'us-east-1',
-  cacheSize: 1000,      // Max items in cache
-  cacheMaxAge: 300000,  // 5 minutes TTL
-});
-
-// Cache reduces S3 API calls for repeated reads
-const data = await storage.get('node:abcd1234...');
-```
-
-### With Custom S3 Client
-
-```typescript
-import { S3Client } from '@aws-sdk/client-s3';
-import { createS3Storage } from '@casfa/storage-s3';
-
-const s3Client = new S3Client({
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'AKIA...',
-    secretAccessKey: '...',
-  },
-});
-
-const storage = createS3Storage({
-  bucket: 'my-cas-bucket',
-  client: s3Client,
-});
-```
-
-## Configuration
-
-```typescript
-interface S3StorageConfig {
-  // Required: S3 bucket name
-  bucket: string;
-  
-  // AWS region (required if not using custom client)
-  region?: string;
-  
-  // Optional: Key prefix for all objects
-  prefix?: string;
-  
-  // Optional: Custom S3 client
-  client?: S3Client;
-  
-  // Optional: Storage class for new objects
-  storageClass?: 'STANDARD' | 'STANDARD_IA' | 'GLACIER' | 'DEEP_ARCHIVE';
-}
-```
-
-### Cache Options
-
-```typescript
-interface S3StorageWithCacheConfig extends S3StorageConfig {
-  // Max items in LRU cache (default: 1000)
-  cacheSize?: number;
-  
-  // Cache TTL in milliseconds (default: 60000)
-  cacheMaxAge?: number;
-}
-```
-
-## S3 Key Structure
-
-Objects are stored with sharded prefixes for better S3 performance:
-
-```
-{prefix}ab/cd/abcd1234...
-```
-
-Where `ab` and `cd` are the first 4 characters of the hash, providing good distribution across S3 partitions.
-
-## API Reference
-
-### Functions
-
-- `createS3Storage(config)` - Create S3 storage without cache
-- `createS3StorageWithCache(config)` - Create S3 storage with LRU cache
-
-### StorageProvider Interface
-
-```typescript
-interface StorageProvider {
-  get(key: string): Promise<Uint8Array | null>;
-  put(key: string, data: Uint8Array): Promise<void>;
-  has(key: string): Promise<boolean>;
-  delete(key: string): Promise<boolean>;
-}
-```
-
-## AWS Permissions
-
-Required IAM permissions for the S3 bucket:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "s3:GetObject",
-        "s3:PutObject",
-        "s3:DeleteObject",
-        "s3:HeadObject"
-      ],
-      "Resource": "arn:aws:s3:::my-cas-bucket/*"
-    }
-  ]
-}
-```
-
-## Performance Tips
-
-1. **Use caching** to reduce S3 API calls and latency
-2. **Use S3 Transfer Acceleration** for global access
-3. **Choose appropriate storage class** based on access patterns
-4. **Enable S3 Intelligent-Tiering** for cost optimization
-5. **Use regional endpoints** to minimize latency
-
-## Cost Considerations
-
-- CAS data is immutable, so versioning is not needed
-- Consider S3 Intelligent-Tiering for infrequently accessed data
-- Monitor PUT/GET request costs for high-throughput workloads
-
-## Related Packages
-
-- `@casfa/storage-core` - Core types and utilities
-- `@casfa/storage-fs` - File system storage (for local deployment)
-- `@casfa/storage-memory` - In-memory storage (for testing)
-
-## License
-
-MIT

package/README.zh-CN.md

@@ -1,182 +0,0 @@
-# @casfa/storage-s3
-
-基于 S3 的 CAS 存储提供者。
-
-## 安装
-
-```bash
-bun add @casfa/storage-s3
-```
-
-## 概述
-
-基于 S3 的 CAS（内容寻址存储）存储提供者。适用于对高可用性和数据持久性有要求的云端部署。
-
-## 使用方法
-
-### 基本用法
-
-```typescript
-import { createS3Storage } from '@casfa/storage-s3';
-
-const storage = createS3Storage({
-  bucket: 'my-cas-bucket',
-  region: 'us-east-1',
-  prefix: 'cas/',  // 可选的键前缀
-});
-
-// 存储数据
-await storage.put('node:abcd1234...', data);
-
-// 检索数据
-const data = await storage.get('node:abcd1234...');
-
-// 检查是否存在
-const exists = await storage.has('node:abcd1234...');
-
-// 删除
-const deleted = await storage.delete('node:abcd1234...');
-```
-
-### 带 LRU 缓存
-
-```typescript
-import { createS3StorageWithCache } from '@casfa/storage-s3';
-
-const storage = createS3StorageWithCache({
-  bucket: 'my-cas-bucket',
-  region: 'us-east-1',
-  cacheSize: 1000,      // 缓存最大条目数
-  cacheMaxAge: 300000,  // 5 分钟 TTL
-});
-
-// 缓存减少 S3 API 调用，降低重复读取延迟
-const data = await storage.get('node:abcd1234...');
-```
-
-### 使用自定义 S3 客户端
-
-```typescript
-import { S3Client } from '@aws-sdk/client-s3';
-import { createS3Storage } from '@casfa/storage-s3';
-
-const s3Client = new S3Client({
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'AKIA...',
-    secretAccessKey: '...',
-  },
-});
-
-const storage = createS3Storage({
-  bucket: 'my-cas-bucket',
-  client: s3Client,
-});
-```
-
-## 配置
-
-```typescript
-interface S3StorageConfig {
-  // 必需：S3 桶名称
-  bucket: string;
-  
-  // AWS 区域（不使用自定义客户端时必需）
-  region?: string;
-  
-  // 可选：所有对象的键前缀
-  prefix?: string;
-  
-  // 可选：自定义 S3 客户端
-  client?: S3Client;
-  
-  // 可选：新对象的存储类别
-  storageClass?: 'STANDARD' | 'STANDARD_IA' | 'GLACIER' | 'DEEP_ARCHIVE';
-}
-```
-
-### 缓存选项
-
-```typescript
-interface S3StorageWithCacheConfig extends S3StorageConfig {
-  // LRU 缓存最大条目数（默认: 1000）
-  cacheSize?: number;
-  
-  // 缓存 TTL，单位毫秒（默认: 60000）
-  cacheMaxAge?: number;
-}
-```
-
-## S3 键结构
-
-对象使用分片前缀存储，以获得更好的 S3 性能：
-
-```
-{prefix}ab/cd/abcd1234...
-```
-
-其中 `ab` 和 `cd` 是哈希的前 4 个字符，可在 S3 分区间提供良好的分布。
-
-## API 参考
-
-### 函数
-
-- `createS3Storage(config)` - 创建不带缓存的 S3 存储
-- `createS3StorageWithCache(config)` - 创建带 LRU 缓存的 S3 存储
-
-### StorageProvider 接口
-
-```typescript
-interface StorageProvider {
-  get(key: string): Promise<Uint8Array | null>;
-  put(key: string, data: Uint8Array): Promise<void>;
-  has(key: string): Promise<boolean>;
-  delete(key: string): Promise<boolean>;
-}
-```
-
-## AWS 权限
-
-S3 桶所需的 IAM 权限：
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "s3:GetObject",
-        "s3:PutObject",
-        "s3:DeleteObject",
-        "s3:HeadObject"
-      ],
-      "Resource": "arn:aws:s3:::my-cas-bucket/*"
-    }
-  ]
-}
-```
-
-## 性能建议
-
-1. **使用缓存** 以减少 S3 API 调用和延迟
-2. **使用 S3 Transfer Acceleration** 以实现全球访问
-3. **根据访问模式选择合适的存储类别**
-4. **启用 S3 Intelligent-Tiering** 以优化成本
-5. **使用区域端点** 以最小化延迟
-
-## 成本考虑
-
-- CAS 数据是不可变的，因此不需要版本控制
-- 对于不常访问的数据，考虑使用 S3 Intelligent-Tiering
-- 对于高吞吐量工作负载，注意监控 PUT/GET 请求费用
-
-## 相关包
-
-- `@casfa/storage-core` - 核心类型与工具
-- `@casfa/storage-fs` - 文件系统存储（用于本地部署）
-- `@casfa/storage-memory` - 内存存储（用于测试）
-
-## 许可证
-
-MIT