ac-storage 0.14.0 → 0.15.0

package/AMBIGUOUS_TESTS_REPORT.md

@@ -0,0 +1,57 @@
+# 모호한 테스트 보고서
+
+## 1. electron-ipc-simulation.test.ts
+
+### 제거 권장 (버그 재현용):
+- **라인 240-305**: `test('CRITICAL: 동시 save() 호출로 인한 race condition')`
+  - 50번 반복하여 손상 재현 시도
+  - json-accessor v0.7에서 이미 해결됨
+  
+- **라인 631-690**: `test('CRITICAL: 빠른 IPC 요청으로 동시 writeFile 유발')`
+  - 100번 반복하여 파일 손상 재현 시도
+  - 이미 해결된 문제
+
+- **라인 784-820**: `test('문서화: IPC 환경 특유의 문제점')`
+  - 단순 console.log만 출력
+  - `expect(true).toBe(true)` - 의미 없는 검증
+  - 코드 주석이나 문서로 대체 가능
+
+### 판단: 3개 테스트 제거하고 나머지 유지
+
+---
+
+## 2. storage-move.test.ts
+
+### 제거 권장:
+- **라인 97-99**: `test('copy 123')`
+  ```typescript
+  test(`copy 123`, async () => {
+      await storage.access('text1:index.txt', 'text');
+  });
+  ```
+  - 의미 없는 테스트명
+  - 불완전한 구현 (access만 하고 아무것도 검증 안 함)
+  - 작성 중 방치된 것으로 보임
+
+### 판단: 해당 테스트 제거
+
+---
+
+## 3. idempotent-operations.test.ts
+- **명확함**: 멱등성 검증, 유지 권장
+
+## 4. 나머지 테스트들
+- **명확함**: 정상적인 기능 테스트
+
+---
+
+## 요약
+
+### 제거 대상 (총 4개 테스트):
+1. `electron-ipc-simulation.test.ts` 내 3개 CRITICAL/문서화 테스트
+2. `storage-move.test.ts` 내 'copy 123' 테스트
+
+### 제거 후:
+- 더 명확한 테스트 스위트
+- 실제 기능 검증에 집중
+- 유지보수 부담 감소

package/CLAUDE.md

@@ -0,0 +1,415 @@
+# AC-Storage - Developer Documentation
+
+## Project Overview
+
+**AC-Storage** is a TypeScript library that provides a structured, access-controlled file storage management system. It allows developers to define file access permissions upfront and manage JSON, text, and binary files in a type-safe manner with transactional semantics.
+
+### Key Features
+
+- **Access Control**: Pre-register file paths and access types before use
+- **Multiple File Formats**: Built-in support for JSON, Text, and Binary files
+- **Custom Accessors**: Extensible system for custom file formats
+- **Transactional Semantics**: Commit changes explicitly to filesystem
+- **Caching System**: Optimized access type validation through `.acstorage` cache
+- **Sub-Storage**: Create isolated storage spaces for directory-based operations
+- **Dependency Tracking**: Automatic management of file dependencies
+
+## Directory Structure
+
+```
+ac-storage/
+├── src/
+│   ├── features/              # Core feature implementations
+│   │   ├── accessors/         # File accessor implementations
+│   │   │   ├── BinaryAccessor/    # Binary file handling
+│   │   │   ├── TextAccessor/      # Text file handling
+│   │   │   ├── JSONAccessor/      # JSON file handling
+│   │   │   ├── CustomAccessor/    # Custom format support
+│   │   │   └── MetaAccessor/      # Directory and root accessors
+│   │   ├── storage/           # Storage management
+│   │   │   ├── ACStorage.ts       # Main storage class
+│   │   │   ├── ACSubStorage.ts    # Sub-storage implementation
+│   │   │   ├── MemACStorage.ts    # In-memory storage
+│   │   │   └── test/              # Storage tests
+│   │   ├── StorageAccessControl/  # Access control logic
+│   │   │   ├── StorageAccessControl.ts
+│   │   │   └── StorageAccessControl.test.ts
+│   │   └── StorageAccess/     # Access type definitions
+│   │       └── StorageAccess.ts
+│   ├── types/                 # TypeScript type definitions
+│   ├── errors/                # Error classes
+│   ├── utils/                 # Utility functions
+│   └── data/                  # Test data
+├── dist/                      # Build output
+├── _TESTPATH/                 # Test runtime directory
+├── jest.config.ts             # Jest test configuration
+├── tsconfig.json              # TypeScript configuration
+├── rollup.config.js           # Build configuration
+└── package.json               # Package metadata
+```
+
+## Architecture
+
+### Core Components
+
+1. **ACStorage** (`src/features/storage/ACStorage.ts`)
+   - Main entry point for storage operations
+   - Manages accessor lifecycle and dependencies
+   - Handles caching and filesystem synchronization
+   - Provides memory management through release/drop operations
+
+2. **StorageAccessControl** (`src/features/StorageAccessControl/`)
+   - Enforces access permissions
+   - Validates file access against registered tree
+   - Manages file operations (copy, move)
+   - Handles destroy operations for memory cleanup
+
+3. **Accessors** (`src/features/accessors/`)
+   - Abstract file operations for different formats
+   - Each type has a Manager and Accessor class
+   - Manager handles lifecycle, Accessor provides API
+
+4. **StorageAccess** (`src/features/StorageAccess/`)
+   - Factory for creating access type definitions
+   - Used in `register()` to define file permissions
+
+### Data Flow
+
+```
+User Code
+    ↓
+ACStorage.register() → Define access tree
+    ↓
+ACStorage.create*() / open*() / access*() → Request file access
+    ↓
+StorageAccessControl → Validate permissions
+    ↓
+AccessorManager → Create/load accessor
+    ↓
+Accessor API → Read/write operations
+    ↓
+ACStorage.commit() → Persist to filesystem
+    ↓
+ACStorage.release() → Save and unload from memory (optional)
+ACStorage.drop() → Delete file and unload (alternative)
+```
+
+### File Access Methods
+
+AC-Storage provides three distinct methods for accessing files, each with different semantics:
+
+#### 1. **create()** - Create Only
+- **Creates** a new file
+- **Throws error** if file already exists (on disk or in memory)
+- Use when you want to ensure you're creating a new file
+
+#### 2. **open()** - Load Only
+- **Loads** an existing file
+- **Throws error** if file does not exist
+- Use when you expect the file to already exist
+
+#### 3. **access()** - Create or Load (Default)
+- **Creates** file if it doesn't exist
+- **Loads** file if it already exists
+- **Never throws** for existence checks
+- Use for flexible access (most common)
+
+#### Access Methods Comparison
+
+| Method | Creates if Missing | Loads if Exists | Error if Missing | Error if Exists |
+|--------|-------------------|-----------------|------------------|-----------------|
+| `create()` | ✅ | ❌ | N/A | ✅ |
+| `open()` | ❌ | ✅ | ✅ | N/A |
+| `access()` | ✅ | ✅ | ❌ | ❌ |
+
+**Example:**
+```typescript
+// Create only - explicit file creation
+const config = await storage.createAsJSON('config.json');
+config.setOne('version', '1.0');
+
+// Open only - explicit file loading
+const existing = await storage.openAsJSON('config.json');
+console.log(existing.getOne('version'));
+
+// Access - flexible (creates or loads)
+const flexible = await storage.accessAsJSON('settings.json');
+```
+
+**Available methods for each approach:**
+```typescript
+// CREATE methods
+await storage.create(identifier, accessType)
+await storage.createAsJSON(identifier)
+await storage.createAsText(identifier)
+await storage.createAsBinary(identifier)
+
+// OPEN methods
+await storage.open(identifier, accessType)
+await storage.openAsJSON(identifier)
+await storage.openAsText(identifier)
+await storage.openAsBinary(identifier)
+
+// ACCESS methods (backward compatible)
+await storage.access(identifier, accessType)
+await storage.accessAsJSON(identifier)
+await storage.accessAsText(identifier)
+await storage.accessAsBinary(identifier)
+```
+
+### Memory Management
+
+AC-Storage provides two approaches for unloading files from memory:
+
+#### 1. **release()** - Save and Unload
+- Commits changes to filesystem
+- Removes accessor from memory
+- **Keeps file on disk**
+- Use when you want to free memory but preserve data
+
+#### 2. **drop()** - Delete and Unload  
+- **Does NOT commit changes** (uncommitted changes are lost)
+- Removes accessor from memory
+- **Deletes file from disk**
+- Use when you want to completely remove the file
+
+#### Comparison Table
+
+| Operation | Commits Changes | Removes from Memory | Deletes File |
+|-----------|----------------|---------------------|--------------|
+| `commit()` | ✅ | ❌ | ❌ |
+| `release()` | ✅ | ✅ | ❌ |
+| `drop()` | ❌ | ✅ | ✅ |
+
+**Example:**
+```typescript
+// Save and unload from memory (file persists)
+await storage.accessAsJSON('config.json');
+await storage.release('config.json');
+
+// Delete file and unload
+await storage.accessAsJSON('temp.json');
+await storage.drop('temp.json');
+```
+
+### Internal Events
+
+The library uses an internal event system for lifecycle management:
+
+- **`'access'` event**: Fired when a file is accessed
+- **`'destroy'` event**: Fired when a file is dropped (deleted)
+- **Note**: `release()` does NOT trigger destroy event (it's a safe unload)
+
+**Usage:**
+```typescript
+storage.addListener('access', (identifier) => {
+    console.log(`Accessed: ${identifier}`);
+});
+
+storage.addListener('destroy', (identifier) => {
+    console.log(`Destroyed: ${identifier}`);
+});
+```
+
+## Testing
+
+### Test Configuration
+
+- **Framework**: Jest with ts-jest
+- **Location**: Tests are colocated with source code
+- **Pattern**: `**/*.(spec|test).ts`
+- **Environment**: Node.js
+
+### Test Files
+
+#### Accessor Tests
+- `src/features/accessors/BinaryAccessor/binary-accessor.test.ts` - Binary file operations
+- `src/features/accessors/TextAccessor/text-accessor.test.ts` - Text file operations
+- `src/features/accessors/JSONAccessor/json-accesssor.test.ts` - JSON file operations
+
+#### Storage Tests
+- `src/features/storage/test/storage.test.ts` - Core storage functionality
+- `src/features/storage/test/storage-accessor.test.ts` - Accessor lifecycle
+- `src/features/storage/test/storage-fs.test.ts` - Filesystem operations
+- `src/features/storage/test/storage-move.test.ts` - Move/copy operations
+- `src/features/storage/test/ac-drop.test.ts` - Drop/destroy operations (memory cleanup)
+- `src/features/storage/test/release.test.ts` - Release operations (save & unload)
+- `src/features/storage/test/access-separation.test.ts` - Create/Open/Access API separation
+- `src/features/storage/test/custom-accessor.test.ts` - Custom accessor support
+- `src/features/storage/test/substorage.test.ts` - Sub-storage functionality
+
+#### Access Control Tests
+- `src/features/StorageAccessControl/StorageAccessControl.test.ts` - Access control logic
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- storage.test.ts
+```
+
+### Test Output Location
+
+Test artifacts and temporary files are created in:
+- `_TESTPATH/` - Runtime test directory (gitignored)
+- Individual tests may create temporary subdirectories
+
+## Building
+
+### Build Configuration
+
+- **Bundler**: Rollup
+- **Output Formats**: 
+  - CommonJS: `dist/bundle.cjs`
+  - ES Module: `dist/bundle.mjs`
+  - TypeScript Declarations: `dist/index.d.ts`
+
+### Build Commands
+
+```bash
+# Build the library
+npm run build
+
+# Run playground example
+npm run playground
+
+# Publish to npm
+npm run publish-public
+```
+
+### Path Aliases
+
+The project uses TypeScript path aliases for cleaner imports:
+
+```typescript
+@/*          → src/*
+types        → src/types/index
+errors       → src/errors/index
+features/*   → src/features/*
+data/*       → src/data/*
+utils        → src/utils/index
+```
+
+Both `tsconfig.json` and `jest.config.ts` must be kept in sync for these aliases.
+
+## Development Guidelines
+
+### Adding New Accessor Types
+
+1. Create accessor directory under `src/features/accessors/`
+2. Implement `IAccessorManager` and accessor interface
+3. Add tests in the same directory
+4. Export from `src/features/accessors/index.ts`
+
+### Adding Tests
+
+1. Place tests near the code they test
+2. Use `.test.ts` suffix
+3. Follow existing test patterns
+4. Ensure all async operations are properly awaited
+5. Clean up test artifacts in `_TESTPATH/`
+
+### Code Style
+
+- TypeScript strict mode enabled (with some relaxations)
+- No implicit any allowed for complex types
+- Explicit method overrides required
+- Property access from index signatures restricted
+
+## Common Issues
+
+### Cache-Related Issues
+
+If tests fail due to cache conflicts:
+```bash
+# Clear test cache
+rm -rf _TESTPATH/
+```
+
+### Build Issues
+
+If build fails:
+```bash
+# Clean and rebuild
+rm -rf dist/
+npm run build
+```
+
+### Test Failures
+
+If tests hang or fail inconsistently:
+- Check for uncommitted accessors
+- Ensure proper cleanup in test teardown
+- Verify `_TESTPATH/` is empty between runs
+
+## Dependencies
+
+### Runtime Dependencies
+- `@hve/json-accessor` - JSON manipulation
+- `fast-deep-equal` - Deep equality checks
+- `tree-navigate` - Tree structure navigation
+
+### Development Dependencies
+- `typescript` - TypeScript compiler
+- `jest` / `ts-jest` - Testing framework
+- `rollup` - Module bundler
+- `tsx` - TypeScript execution for playground
+
+## Version
+
+Current version: **0.15.0** (unreleased)
+
+Last updated: 2025-12-07
+
+## Recent Changes
+
+### v0.15.0 - Access API Separation & Release API (2025-12-07)
+
+**Breaking Changes:**
+- Renamed internal event `'release'` → `'destroy'` (v0.14.1)
+  - `storage.addListener('release', ...)` → `storage.addListener('destroy', ...)`
+
+**New Features:**
+
+1. **File Access Method Separation**
+   - `create()` / `createAsJSON()` / `createAsText()` / `createAsBinary()` - Create new files only (error if exists)
+   - `open()` / `openAsJSON()` / `openAsText()` / `openAsBinary()` - Load existing files only (error if missing)
+   - `access()` / `accessAsJSON()` / `accessAsText()` / `accessAsBinary()` - Flexible access (create or load)
+
+2. **Memory Management APIs** (v0.14.1+)
+   - `release(identifier)` - Save changes and unload file from memory (file persists)
+   - `releaseDir(identifier)` - Save and unload directory from memory
+   - `releaseAll()` - Save and unload all files from memory
+
+**Internal Changes:**
+- Refactored `getOrCreateAccessor()` to support three access modes: `'create'`, `'open'`, `'access'`
+- Added `getOrCreateAccessorFromAccess()` helper method
+- Added `validateAccess()` to `StorageAccessControl` for permission validation without accessor creation
+- Updated all internal event listeners to use `'destroy'` terminology
+
+**Backward Compatibility:**
+- All existing `access*()` methods continue to work with the same behavior
+- No breaking changes to public API (except event name change in v0.14.1)
+
+**Example:**
+```typescript
+// New explicit methods
+const config = await storage.createAsJSON('config.json');  // Create only
+const existing = await storage.openAsJSON('config.json');  // Load only
+
+// Existing flexible method (backward compatible)
+const flexible = await storage.accessAsJSON('settings.json'); // Create or load
+
+// Memory management
+await storage.release('config.json');  // Save and unload (v0.14.1+)
+await storage.drop('temp.json');       // Delete and unload
+```