packages/frontend/lib/features/project/data/project_store.dart

import '../models/persisted_project.dart';

/// An abstract interface defining the storage operations for project records.
///
/// Implementations of this interface (such as IndexedDB storage) are responsible
/// for persisting project data (metadata and file archive contents) to a local
/// or remote database.
abstract interface class ProjectStore {
  /// Retrieves a specific [PersistedProject] record by its unique ID,
  /// including the full archive data.
  ///
  /// Returns `null` if no project exists with the given ID.
  Future<PersistedProject?> getProject(String id);

  /// Retrieves only the metadata for a project (without the ZIP archive).
  ///
  /// The returned [PersistedProject] will have a `null` [PersistedProject.archive].
  /// Returns `null` if no project exists with the given ID.
  Future<PersistedProject?> getProjectMeta(String id);

  /// Lists all projects stored in the database (metadata only).
  ///
  /// The returned projects have `null` [PersistedProject.archive] fields.
  /// The list is sorted by last opened timestamp in descending order.
  Future<List<PersistedProject>> listProjects();

  /// Saves or updates a [PersistedProject] record in the database.
  ///
  /// If [PersistedProject.archive] is non-null, both metadata and archive data
  /// are written. If it is `null`, only the metadata is updated and any
  /// existing archive in storage is preserved.
  Future<void> putProject(PersistedProject project);

  /// Deletes a project record from the database by its unique ID.
  Future<void> deleteProject(String id);
}