@casfa/storage-fs 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @casfa/storage-fs
+
+File system storage provider for CAS.
+
+## Installation
+
+```bash
+bun add @casfa/storage-fs
+```
+
+## Overview
+
+A file system-backed storage provider for CAS (Content-Addressable Storage). Stores content in a sharded directory structure for efficient file system performance.
+
+### Storage Structure
+
+```
+{basePath}/
+├── ab/
+│   └── cd/
+│       └── abcd1234...  (full hash)
+├── ef/
+│   └── 01/
+│       └── ef012345...
+└── ...
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createFsStorage } from '@casfa/storage-fs';
+
+const storage = createFsStorage({
+  basePath: '/var/cas/data',
+});
+
+// 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 { createFsStorageWithCache } from '@casfa/storage-fs';
+
+const storage = createFsStorageWithCache({
+  basePath: '/var/cas/data',
+  cacheSize: 1000,      // Max items in cache
+  cacheMaxAge: 60000,   // TTL in milliseconds
+});
+
+// Cache is automatically managed
+const data = await storage.get('node:abcd1234...');  // May hit cache
+```
+
+## Configuration
+
+```typescript
+interface FsStorageConfig {
+  // Required: Base directory for storage
+  basePath: string;
+  
+  // Optional: File permissions (default: 0o644)
+  fileMode?: number;
+  
+  // Optional: Directory permissions (default: 0o755)
+  dirMode?: number;
+}
+```
+
+### Cache Options
+
+```typescript
+interface FsStorageWithCacheConfig extends FsStorageConfig {
+  // Max items in LRU cache (default: 1000)
+  cacheSize?: number;
+  
+  // Cache TTL in milliseconds (default: 60000)
+  cacheMaxAge?: number;
+}
+```
+
+## API Reference
+
+### Functions
+
+- `createFsStorage(config)` - Create storage without cache
+- `createFsStorageWithCache(config)` - Create 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>;
+}
+```
+
+## Performance Tips
+
+1. **Use caching** for read-heavy workloads
+2. **Use SSD storage** for better random access performance
+3. **Monitor disk space** as CAS data is append-only by nature
+4. Consider **separate partitions** for CAS data to prevent filling system disk
+
+## Related Packages
+
+- `@casfa/storage-core` - Core types and utilities
+- `@casfa/storage-memory` - In-memory storage (for testing)
+- `@casfa/storage-s3` - S3 storage (for cloud deployment)
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,127 @@
+# @casfa/storage-fs
+
+基于文件系统的 CAS 存储提供者。
+
+## 安装
+
+```bash
+bun add @casfa/storage-fs
+```
+
+## 概述
+
+基于文件系统的 CAS（内容寻址存储）存储提供者。采用分片目录结构存储内容，以获得更好的文件系统性能。
+
+### 存储结构
+
+```
+{basePath}/
+├── ab/
+│   └── cd/
+│       └── abcd1234...  (full hash)
+├── ef/
+│   └── 01/
+│       └── ef012345...
+└── ...
+```
+
+## 使用方法
+
+### 基本用法
+
+```typescript
+import { createFsStorage } from '@casfa/storage-fs';
+
+const storage = createFsStorage({
+  basePath: '/var/cas/data',
+});
+
+// 存储数据
+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 { createFsStorageWithCache } from '@casfa/storage-fs';
+
+const storage = createFsStorageWithCache({
+  basePath: '/var/cas/data',
+  cacheSize: 1000,      // 缓存最大条目数
+  cacheMaxAge: 60000,   // TTL（毫秒）
+});
+
+// 缓存自动管理
+const data = await storage.get('node:abcd1234...');  // 可能命中缓存
+```
+
+## 配置
+
+```typescript
+interface FsStorageConfig {
+  // 必需：存储基础目录
+  basePath: string;
+  
+  // 可选：文件权限（默认: 0o644）
+  fileMode?: number;
+  
+  // 可选：目录权限（默认: 0o755）
+  dirMode?: number;
+}
+```
+
+### 缓存选项
+
+```typescript
+interface FsStorageWithCacheConfig extends FsStorageConfig {
+  // LRU 缓存最大条目数（默认: 1000）
+  cacheSize?: number;
+  
+  // 缓存 TTL，单位毫秒（默认: 60000）
+  cacheMaxAge?: number;
+}
+```
+
+## API 参考
+
+### 函数
+
+- `createFsStorage(config)` - 创建不带缓存的存储
+- `createFsStorageWithCache(config)` - 创建带 LRU 缓存的存储
+
+### 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>;
+}
+```
+
+## 性能建议
+
+1. **使用缓存** 以应对读密集型工作负载
+2. **使用 SSD 存储** 以获得更好的随机访问性能
+3. **监控磁盘空间**，因为 CAS 数据本质上是只追加的
+4. 考虑为 CAS 数据使用**独立分区**，防止占满系统磁盘
+
+## 相关包
+
+- `@casfa/storage-core` - 核心类型与工具
+- `@casfa/storage-memory` - 内存存储（用于测试）
+- `@casfa/storage-s3` - S3 存储（用于云端部署）
+
+## 许可证
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { StorageProvider } from '@casfa/storage-core';
+
+/**
+ * File System Storage Provider for CAS
+ *
+ * Implements StorageProvider with:
+ * - LRU cache for key existence checks
+ * - Local file system backend storage
+ * - Automatic directory creation
+ */
+
+/**
+ * File System Storage configuration
+ */
+type FsStorageConfig = {
+    /** Base directory for storage */
+    basePath: string;
+    /** LRU cache size for key existence (default: 10000) */
+    cacheSize?: number;
+    /** Key prefix in storage (default: "cas/sha256/") */
+    prefix?: string;
+};
+/**
+ * Create a file system-backed storage provider
+ */
+declare const createFsStorage: (config: FsStorageConfig) => StorageProvider;
+/**
+ * Create file system storage with cache control methods (for testing)
+ */
+declare const createFsStorageWithCache: (config: FsStorageConfig) => {
+    clearCache: () => void;
+    getCacheStats: () => {
+        size: number;
+    };
+    has: (key: string) => Promise<boolean>;
+    get: (key: string) => Promise<Uint8Array | null>;
+    put: (key: string, value: Uint8Array) => Promise<void>;
+};
+
+export { type FsStorageConfig, createFsStorage, createFsStorageWithCache };

package/dist/index.js

@@ -0,0 +1,77 @@
+// src/fs-storage.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import {
+  createLRUCache,
+  DEFAULT_CACHE_SIZE,
+  toStoragePath
+} from "@casfa/storage-core";
+var createFsStorage = (config) => {
+  const basePath = config.basePath;
+  const prefix = config.prefix ?? "cas/sha256/";
+  const existsCache = createLRUCache(config.cacheSize ?? DEFAULT_CACHE_SIZE);
+  if (!existsSync(basePath)) {
+    mkdirSync(basePath, { recursive: true });
+  }
+  const toFilePath = (casKey) => {
+    const storagePath = toStoragePath(casKey, prefix);
+    return join(basePath, storagePath);
+  };
+  const has = async (key) => {
+    const cached = existsCache.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const filePath = toFilePath(key);
+    const exists = existsSync(filePath);
+    if (exists) {
+      existsCache.set(key, true);
+    }
+    return exists;
+  };
+  const get = async (key) => {
+    const filePath = toFilePath(key);
+    try {
+      const buffer = readFileSync(filePath);
+      existsCache.set(key, true);
+      return new Uint8Array(buffer);
+    } catch (error) {
+      const err = error;
+      if (err.code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    }
+  };
+  const put = async (key, value) => {
+    if (existsCache.get(key)) {
+      return;
+    }
+    const exists = await has(key);
+    if (exists) {
+      return;
+    }
+    const filePath = toFilePath(key);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filePath, value);
+    existsCache.set(key, true);
+  };
+  return { has, get, put };
+};
+var createFsStorageWithCache = (config) => {
+  const existsCache = createLRUCache(config.cacheSize ?? DEFAULT_CACHE_SIZE);
+  const storage = createFsStorage(config);
+  return {
+    ...storage,
+    clearCache: () => existsCache.clear(),
+    getCacheStats: () => ({ size: existsCache.size() })
+  };
+};
+export {
+  createFsStorage,
+  createFsStorageWithCache
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fs-storage.ts"],"sourcesContent":["/**\n * File System Storage Provider for CAS\n *\n * Implements StorageProvider with:\n * - LRU cache for key existence checks\n * - Local file system backend storage\n * - Automatic directory creation\n */\n\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport {\n  createLRUCache,\n  DEFAULT_CACHE_SIZE,\n  type StorageProvider,\n  toStoragePath,\n} from \"@casfa/storage-core\";\n\n/**\n * File System Storage configuration\n */\nexport type FsStorageConfig = {\n  /** Base directory for storage */\n  basePath: string;\n  /** LRU cache size for key existence (default: 10000) */\n  cacheSize?: number;\n  /** Key prefix in storage (default: \"cas/sha256/\") */\n  prefix?: string;\n};\n\n/**\n * Create a file system-backed storage provider\n */\nexport const createFsStorage = (config: FsStorageConfig): StorageProvider => {\n  const basePath = config.basePath;\n  const prefix = config.prefix ?? \"cas/sha256/\";\n  const existsCache = createLRUCache<string, boolean>(config.cacheSize ?? DEFAULT_CACHE_SIZE);\n\n  // Ensure base directory exists\n  if (!existsSync(basePath)) {\n    mkdirSync(basePath, { recursive: true });\n  }\n\n  const toFilePath = (casKey: string): string => {\n    const storagePath = toStoragePath(casKey, prefix);\n    return join(basePath, storagePath);\n  };\n\n  const has = async (key: string): Promise<boolean> => {\n    // Check cache first\n    const cached = existsCache.get(key);\n    if (cached !== undefined) {\n      return cached;\n    }\n\n    // Check file system\n    const filePath = toFilePath(key);\n    const exists = existsSync(filePath);\n\n    if (exists) {\n      existsCache.set(key, true);\n    }\n    // Don't cache non-existence (it might be written later)\n\n    return exists;\n  };\n\n  const get = async (key: string): Promise<Uint8Array | null> => {\n    const filePath = toFilePath(key);\n\n    try {\n      const buffer = readFileSync(filePath);\n      // Mark as existing in cache\n      existsCache.set(key, true);\n      return new Uint8Array(buffer);\n    } catch (error: unknown) {\n      const err = error as { code?: string };\n      if (err.code === \"ENOENT\") {\n        return null;\n      }\n      throw error;\n    }\n  };\n\n  const put = async (key: string, value: Uint8Array): Promise<void> => {\n    // Check cache first (avoid redundant writes)\n    if (existsCache.get(key)) {\n      return;\n    }\n\n    // Check if already exists\n    const exists = await has(key);\n    if (exists) {\n      return;\n    }\n\n    const filePath = toFilePath(key);\n    const dir = dirname(filePath);\n\n    // Ensure directory exists\n    if (!existsSync(dir)) {\n      mkdirSync(dir, { recursive: true });\n    }\n\n    // Write file\n    writeFileSync(filePath, value);\n\n    // Mark as existing\n    existsCache.set(key, true);\n  };\n\n  return { has, get, put };\n};\n\n/**\n * Create file system storage with cache control methods (for testing)\n */\nexport const createFsStorageWithCache = (config: FsStorageConfig) => {\n  const existsCache = createLRUCache<string, boolean>(config.cacheSize ?? DEFAULT_CACHE_SIZE);\n\n  const storage = createFsStorage(config);\n\n  return {\n    ...storage,\n    clearCache: () => existsCache.clear(),\n    getCacheStats: () => ({ size: existsCache.size() }),\n  };\n};\n"],"mappings":";AASA,SAAS,YAAY,WAAW,cAAc,qBAAqB;AACnE,SAAS,SAAS,YAAY;AAC9B;AAAA,EACE;AAAA,EACA;AAAA,EAEA;AAAA,OACK;AAiBA,IAAM,kBAAkB,CAAC,WAA6C;AAC3E,QAAM,WAAW,OAAO;AACxB,QAAM,SAAS,OAAO,UAAU;AAChC,QAAM,cAAc,eAAgC,OAAO,aAAa,kBAAkB;AAG1F,MAAI,CAAC,WAAW,QAAQ,GAAG;AACzB,cAAU,UAAU,EAAE,WAAW,KAAK,CAAC;AAAA,EACzC;AAEA,QAAM,aAAa,CAAC,WAA2B;AAC7C,UAAM,cAAc,cAAc,QAAQ,MAAM;AAChD,WAAO,KAAK,UAAU,WAAW;AAAA,EACnC;AAEA,QAAM,MAAM,OAAO,QAAkC;AAEnD,UAAM,SAAS,YAAY,IAAI,GAAG;AAClC,QAAI,WAAW,QAAW;AACxB,aAAO;AAAA,IACT;AAGA,UAAM,WAAW,WAAW,GAAG;AAC/B,UAAM,SAAS,WAAW,QAAQ;AAElC,QAAI,QAAQ;AACV,kBAAY,IAAI,KAAK,IAAI;AAAA,IAC3B;AAGA,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,OAAO,QAA4C;AAC7D,UAAM,WAAW,WAAW,GAAG;AAE/B,QAAI;AACF,YAAM,SAAS,aAAa,QAAQ;AAEpC,kBAAY,IAAI,KAAK,IAAI;AACzB,aAAO,IAAI,WAAW,MAAM;AAAA,IAC9B,SAAS,OAAgB;AACvB,YAAM,MAAM;AACZ,UAAI,IAAI,SAAS,UAAU;AACzB,eAAO;AAAA,MACT;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAEA,QAAM,MAAM,OAAO,KAAa,UAAqC;AAEnE,QAAI,YAAY,IAAI,GAAG,GAAG;AACxB;AAAA,IACF;AAGA,UAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,QAAI,QAAQ;AACV;AAAA,IACF;AAEA,UAAM,WAAW,WAAW,GAAG;AAC/B,UAAM,MAAM,QAAQ,QAAQ;AAG5B,QAAI,CAAC,WAAW,GAAG,GAAG;AACpB,gBAAU,KAAK,EAAE,WAAW,KAAK,CAAC;AAAA,IACpC;AAGA,kBAAc,UAAU,KAAK;AAG7B,gBAAY,IAAI,KAAK,IAAI;AAAA,EAC3B;AAEA,SAAO,EAAE,KAAK,KAAK,IAAI;AACzB;AAKO,IAAM,2BAA2B,CAAC,WAA4B;AACnE,QAAM,cAAc,eAAgC,OAAO,aAAa,kBAAkB;AAE1F,QAAM,UAAU,gBAAgB,MAAM;AAEtC,SAAO;AAAA,IACL,GAAG;AAAA,IACH,YAAY,MAAM,YAAY,MAAM;AAAA,IACpC,eAAe,OAAO,EAAE,MAAM,YAAY,KAAK,EAAE;AAAA,EACnD;AACF;","names":[]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@casfa/storage-fs",
+  "version": "0.1.0",
+  "description": "File system storage provider for CAS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "check": "tsc --noEmit && biome check .",
+    "check:fix": "tsc --noEmit && biome check --write .",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@casfa/storage-core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}