Building a Universal Drafts System in a VS Code Extension — Part 1: Types & Storage

n } from './types'; import { createChecksum } from './utils';

export class DraftsService { constructor(private readonly storage: vscode.Memento) {}

async upsert<T>(workspaceId: string, draft: Partial<Draft<T>>): Promise<Draft<T>> { const key = draft:${workspaceId}:${draft.meta?.id ?? crypto.randomUUID()}; const existing = await this.storage.get<Draft<T>>(key);

const version = existing ? existing.meta.version + 1 : 1;
const now = Date.now();
const checksum = createChecksum(JSON.stringify(draft.content));

const normalized: Draft<T> = {
  meta: {
    id: draft.meta?.id ?? crypto.randomUUID(),
    workspaceId,
    version,
    createdAt: existing?.meta.createdAt ?? now,
    updatedAt: now,
    checksum,
  },
  content: draft.content ?? ({} as T),
};

await this.storage.update(key, normalized);
return normalized;

}

async load<T>(workspaceId: string, draftId: string): Promise<Draft<T> | undefined> { const key = draft:${workspaceId}:${draftId}; return this.storage.get<Draft<T>>(key); }

async delete(workspaceId: string, draftId: string): Promise<void> { const key = draft:${workspaceId}:${draftId}; await this.storage.update(key, undefined); }

async list(workspaceId: string): Promise<Draft<unknown>[]> { const keys = this.storage.keys(); const prefix = draft:${workspaceId}:; const results: Draft<unknown>[] = [];

for (const key of keys) {
  if (key.startsWith(prefix)) {
    const draft = await this.storage.get<Draft<unknown>>(key);
    if (draft) results.push(draft);
  }
}
return results.sort((a, b) => b.meta.updatedAt - a.meta.updatedAt);

} }

### 3. Architecture Decisions
- **Workspace-Scoped Isolation**: Keys are prefixed with `workspaceId` to prevent cross-workspace state leakage.
- **Optimistic Concurrency**: `version` and `checksum` enable conflict detection without blocking the extension host.
- **Memento Over File I/O**: `vscode.Memento` provides atomic writes, automatic serialization, and respects VS Code's storage quotas.
- **Generic Content Typing**: `Draft<T>` allows strict typing per feature (e.g., `Draft<SnippetConfig>`, `Draft<QueryState>`) while sharing the same storage contract.

## Pitfall Guide
1. **Ignoring Extension Lifecycle Boundaries**: Storing drafts in module-level variables or singletons causes data loss when the extension host restarts. Always persist to `context.globalState` or `workspaceState` immediately after mutation.
2. **Race Conditions in Multi-View Scenarios**: Webviews, tree views, and commands may trigger concurrent saves. Implement version bumping and checksum validation to detect stale writes before committing.
3. **Overusing `globalState` for Workspace-Specific Data**: `globalState` is shared across all workspaces. Drafts must be scoped to `workspaceState` or explicitly namespaced with `workspaceId` to avoid cross-project contamination.
4. **Skipping Schema Validation on Hydration**: Deserialized drafts from storage may contain outdated fields after extension updates. Always run a migration/validation step when loading `Draft<T>` to prevent runtime type errors.
5. **Blocking the Extension Host with Synchronous I/O**: Never use `fs.readFileSync` or synchronous `Memento` patterns. All storage operations must be `async/await` to keep the UI thread responsive and comply with VS Code's threading model.
6. **Unbounded Storage Growth**: Drafts accumulate indefinitely if not garbage-collected. Implement TTL-based cleanup, workspace-scoped pruning, or explicit `delete` triggers to stay within VS Code's storage limits.
7. **Missing Error Boundaries in Upsert Flow**: A failed `storage.update` can leave the UI in an inconsistent state. Wrap upsert operations in try/catch, emit telemetry, and provide fallback UI states (e.g., "Draft saved locally, sync pending").

## Deliverables
- **📐 Architecture Blueprint**: Component diagram mapping `Draft<T>` → `DraftsService` → `vscode.Memento` adapter, including conflict resolution flow, workspace scoping strategy, and lifecycle hooks.
- **✅ Implementation Checklist**: 
  - [ ] Define generic `Draft<T>` interface with metadata contract
  - [ ] Implement versioned upsert with checksum validation
  - [ ] Scope storage keys to `workspaceId`
  - [ ] Add hydration validation & migration pipeline
  - [ ] Configure garbage collection & storage quota monitoring
  - [ ] Wire up to extension activation & dispose lifecycle
- **⚙️ Configuration Templates**: 
  - `package.json` activation events (`onStartupFinished`, `workspaceContains:*.draft`)
  - `tsconfig.json` strict mode settings for generic type safety
  - VS Code `settings.json` schema for draft retention policies & workspace isolation toggles