Interface ISyncBackend

packages/core/src/sync/sync-backend.ts:19–83

/** Unified sync backend interface */
export interface ISyncBackend {
  /** Backend type identifier */
  readonly type: SyncBackendType;

  /** Test if the backend is reachable and credentials are valid */
  testConnection(): Promise<boolean>;

  /** Ensure the remote directory structure exists */
  ensureDirectories(): Promise<void>;

  /** Upload data to a path */
  put(path: string, data: Uint8Array): Promise<void>;

  /** Download data from a path */
  get(path: string): Promise<Uint8Array>;

  /** Download data with progress reporting (optional — falls back to get() if not implemented) */
  getWithProgress?(
    path: string,
    onProgress?: (loaded: number, total: number) => void,
  ): Promise<Uint8Array>;

  /** Upload a local file directly when the platform/backend supports native file transfer. */
  putFile?(
    path: string,
    localFilePath: string,
    onProgress?: (loaded: number, total: number) => void,
  ): Promise<void>;

  /** Download directly into a local file when the platform/backend supports native file transfer. */
  getFileToPath?(
    path: string,
    localFilePath: string,
    onProgress?: (loaded: number, total: number) => void,
  ): Promise<void>;

  /** Get JSON data from a path, returns null if not found */
  getJSON<T>(path: string): Promise<T | null>;

  /** Upload JSON data to a path */
  putJSON<T>(path: string, data: T): Promise<void>;

  /** List directory contents */
  listDir(path: string): Promise<RemoteFile[]>;

  /** Delete a file at the given path */
  delete(path: string): Promise<void>;

  /** Check if a file exists */
  exists(path: string): Promise<boolean>;

  /**
   * Move/rename a file from `fromPath` to `toPath`.
   * Implementations should create intermediate directories on the destination side.
   * Should be atomic where the backend supports it; otherwise copy + delete.
   * Throws if the source does not exist or if the destination already exists.
   */
  move(fromPath: string, toPath: string): Promise<void>;