core-3nweb-client-lib 0.43.19 → 0.44.0

package/build/api-defs/files.d.ts

@@ -84,6 +84,8 @@ declare namespace web3n.files {
 		remoteIsArchived?: true;
 		remoteFolderItemNotFound?: true;
 		overlapsLocalItem?: true;
+		nameOverlaps?: string[];
+		noNamePostfixGiven?: true;
 	}
 
 	/**
@@ -648,6 +650,13 @@ declare namespace web3n.files {
 		 */
 		adoptRemote(opts?: OptionsToAdopteRemote): Promise<void>;
 
+		/**
+		 * Calculates diff between current and remote states of file at given path.
+		 * @param path 
+		 * @param opts 
+		 */
+		diffCurrentAndRemoteVersions(opts?: OptionsToDiffFileVersions): Promise<FileDiff|undefined>;
+
 	}
 
 	interface OptionsToAdopteRemote {
@@ -658,6 +667,11 @@ declare namespace web3n.files {
 		remoteVersion?: number;
 	}
 
+	interface OptionsToDiffFileVersions {
+		remoteVersion?: number;
+		compareContentIfSameMTime?: boolean;
+	}
+
 	interface WritableFileSyncAPI extends ReadonlyFileSyncAPI {
 
 		/**
@@ -1104,6 +1118,127 @@ declare namespace web3n.files {
 
 	}
 
+	interface FSEvent {
+		path: string;
+	}
+
+	interface FSChangeEvent {
+		path: string;
+		src: 'local'|'sync';
+	}
+
+	interface RemovedEvent extends FSChangeEvent {
+		type: 'removed';
+	}
+
+	interface VersionChangeOnUpload extends FSChangeEvent {
+		type: 'version-change-on-upload';
+		src: 'sync';
+		newVersion: number;
+	}
+
+	type FolderEvent = EntryRemovalEvent | EntryAdditionEvent |
+		EntryRenamingEvent | RemovedEvent | VersionChangeOnUpload;
+
+	interface EntryRemovalEvent extends FSChangeEvent {
+		type: 'entry-removal';
+		name: string;
+		moveLabel?: number;
+		newVersion?: number;
+	}
+
+	interface EntryAdditionEvent extends FSChangeEvent {
+		type: 'entry-addition';
+		entry: ListingEntry;
+		moveLabel?: number;
+		newVersion?: number;
+	}
+
+	interface EntryRenamingEvent extends FSChangeEvent {
+		type: 'entry-renaming';
+		oldName: string;
+		newName: string;
+		newVersion?: number;
+	}
+
+	type FileEvent = FileChangeEvent | RemovedEvent | VersionChangeOnUpload;
+
+	interface FileChangeEvent extends FSChangeEvent {
+		type: 'file-change';
+		newVersion?: number;
+	}
+
+	type RemoteEvent = RemoteVersionArchivalEvent | RemoteArchVerRemovalEvent |
+		RemoteRemovalEvent | RemoteChangeEvent;
+
+	interface RemoteVersionArchivalEvent extends FSEvent {
+		type: 'remote-version-archival';
+		archivedVersion: number;
+		syncStatus: SyncStatus;
+	}
+
+	interface RemoteArchVerRemovalEvent extends FSEvent {
+		type: 'remote-arch-ver-removal';
+		removedArchVer: number;
+		syncStatus: SyncStatus;
+	}
+
+	interface RemoteRemovalEvent extends FSEvent {
+		type: 'remote-removal';
+		syncStatus: SyncStatus;
+	}
+
+	interface RemoteChangeEvent extends FSEvent {
+		type: 'remote-change';
+		newRemoteVersion: number;
+		syncStatus: SyncStatus;
+	}
+
+	type UploadEvent = UploadStartEvent | UploadProgressEvent | UploadDoneEvent;
+
+	interface UploadEventBase extends FSEvent {
+		uploadTaskId: number;
+		localVersion: number;
+		uploadVersion: number;
+	}
+
+	interface UploadStartEvent extends UploadEventBase {
+		type: 'upload-started';
+		totalBytesToUpload: number;
+	}
+
+	interface UploadProgressEvent extends UploadEventBase {
+		type: 'upload-progress';
+		totalBytesToUpload: number;
+		bytesLeftToUpload: number;
+	}
+
+	interface UploadDoneEvent extends UploadEventBase {
+		type: 'upload-done';
+	}
+
+	type DownloadEvent = DownloadStartEvent | DownloadProgressEvent | DownloadDoneEvent;
+
+	interface DownloadEventBase extends FSEvent {
+		downloadTaskId: number;
+		version: number;
+	}
+
+	interface DownloadStartEvent extends DownloadEventBase {
+		type: 'download-started';
+		totalBytesToDownload: number;
+	}
+
+	interface DownloadDoneEvent extends DownloadEventBase {
+		type: 'download-done';
+	}
+
+	interface DownloadProgressEvent extends DownloadEventBase {
+		type: 'download-progress';
+		totalBytesToDownload: number;
+		bytesLeftToDownload: number;
+	}
+
 	interface VersionedFileWriteFlags extends FileFlags {
 
 		/**
@@ -1305,6 +1440,15 @@ declare namespace web3n.files {
 		 */
 		diffCurrentAndRemoteFolderVersions(path: string, remoteVersion?: number): Promise<FolderDiff|undefined>;
 
+		/**
+		 * Calculates diff between current and remote states of file at given path.
+		 * @param path 
+		 * @param opts 
+		 */
+		diffCurrentAndRemoteFileVersions(
+			path: string, opts?: OptionsToDiffFileVersions
+		): Promise<FileDiff|undefined>;
+
 		/**
 		 * Returns stats of a child from remote version of a folder.
 		 * @param path of folder
@@ -1342,11 +1486,7 @@ declare namespace web3n.files {
 
 	}
 
-	/**
-	 * Difference between two versions of folder node.
-	 * Folder items that same in both versions are not included.
-	 */
-	interface FolderDiff {
+	interface CommonDiff {
 		/**
 		 * Current version against which this diff is done.
 		 */
@@ -1363,67 +1503,119 @@ declare namespace web3n.files {
 		remoteVersion?: number;
 
 		/**
-		 * Flag indicating if remote version is archived.
-		 * If remote is archived/delete, it has nothing inside, and with this implicit
+		 * Flag indicating if remote version is removed, i.e. has no current version.
+		 * If remote is removed, it has nothing inside, and with this implicit
 		 * understanding there is no need to have other data fields populated here.
 		 */
-		isRemoteArchived: boolean;
+		isRemoteRemoved: boolean;
 
 		/**
-		 * Items present only in current version.
+		 * Synced version against which this diff is done.
 		 */
-		inCurrent?: ListingEntry[];
+		syncedVersion?: number;
 
 		/**
-		 * Items present only in remote version.
+		 * Creation time should always be same, but if not, this field will show different values.
+		 * If remote is removed, this field will be undefined.
 		 */
-		inRemote?: ListingEntry[];
+		ctime?: {
+			remote: Date;
+			current: Date;
+			synced: Date;
+		};
 
 		/**
-		 * Different names are for items that are same nodes but have different names
-		 * in local and remote branches.
+		 * This field shows different modification times. If they are same, field will be undefined.
+		 * If remote is removed, this field will be undefined.
+		 */
+		mtime?: {
+			remote: Date;
+			current: Date;
+			synced: Date;
+		};
+
+		/**
+		 * Difference between xattrs. Same xattrs in both versions are not included.
 		 */
-		differentNames?: {
-			localName: string;
-			remoteName: string;
+		xattrs?: {
+			[name: string]: {
+				addedIn?: 'l'|'r'|'l&r';
+				removedIn?: 'l'|'r';
+				changedIn?: 'l'|'r'|'l&r';
+			};
+		};
+	}
+
+	/**
+	 * Difference of remote and local folder versions expressed as changes relative to synced version.
+	 * 
+	 * Consider the following example.
+	 * There is an item in local version, but not in remote.
+	 * Such difference can come about in two ways: addition in local branch, or removal in remote.
+	 * 
+	 * Contexts where versions are compared need information about change actions in folder.
+	 * Hence, this diff is a three point comparison, yielding richer info.
+	 */
+	interface FolderDiff extends CommonDiff {
+
+		/**
+		 * Items that were removed. Pointing to where removal is done in remote (r), or local (l) branches.
+		 * 
+		 * Consider the following example.
+		 * Item that is removed in local version is present in both remote and synced versions.
+		 * Hence, difference between local and remote versions is due to removal in local branch.
+		 */
+		removed?: {
+			name: string;
+			removedIn: 'l'|'r';
 		}[];
 
 		/**
-		 * Different keys identifies items that have different encryption keys in
-		 * local and remote branches. Keys may be changed, hence, given situation
-		 * should be reflected.
+		 * Items that were renamed. Pointing to where renaming is done in remote (r), or local (l) branches.
+		 * 
+		 * When item is renamed local branch, then local name was changed from synced value,
+		 * while remote name is still equal to synced (older) value.
 		 */
-		differentKeys?: string[];
+		renamed?: {
+			local: string;
+			remote: string;
+			renamedIn: 'l'|'r'|'l&r';
+		}[];
 
 		/**
-		 * Name overlaps are items with same name, but different node objects underneath.
+		 * Items that were added. Pointing to where addition is done in remote (r), or local (l) branches.
+		 * 
+		 * When item added in remote branch, then it is present in remote version under the referenced name.
+		 * Synced (older) state of folder doesn't have it, and neither does local.
 		 */
-		nameOverlaps?: string[];
+		added?: {
+			name: string;
+			addedIn: 'l'|'r';
+		}[];
 
 		/**
-		 * Creation time should always be same.
-		 * But there is no way to enforce it, hence, we have this field.
+		 * Items that reencrypted and now have different keys.
 		 */
-		ctime: {
-			remote?: Date;
-			current: Date;
-		};
+		rekeyed?: {
+			local: string;
+			remote: string;
+			rekeyedIn: 'l'|'r'|'l&r';
+		}[];
 
 		/**
-		 * Modification time most probably be different between versions.
+		 * Name overlaps are items with same name, but different node objects underneath.
 		 */
-		mtime: {
-			remote?: Date;
-			current: Date;
-		};
+		nameOverlaps?: string[];
+	}
 
+	interface FileDiff extends CommonDiff {
+		areContentsSame: boolean;
 		/**
-		 * Difference between xattrs. Same xattrs in both versions are not included.
+		 * If sizes are different this field will have respective values.
 		 */
-		xattrs?: {
-			inCurrent?: { name: string; value: any; }[];
-			inRemote?: { name: string; value: any; }[];
-			nameOverlaps?: string[];
+		size?: {
+			remote: number;
+			current: number;
 		};
 	}
 
@@ -1465,12 +1657,14 @@ declare namespace web3n.files {
 
 		/**
 		 * This method is for resolving conflicts on folders.
-		 * It adopts all folder items, that are present in remote version and are missing in local version.
+		 * It merges folder changes from remote version.
 		 * Returns new local version, if there were remote items to adopt and their were added to local state.
 		 * @param path 
 		 * @param opts
 		 */
-		adoptAllRemoteItems(path: string, opts?: OptionsToAdoptAllRemoteItems): Promise<number|undefined>;
+		mergeFolderCurrentAndRemoteVersions(
+			path: string, opts?: OptionsToMergeFolderVersions
+		): Promise<number|undefined>;
 
 	}
 
@@ -1494,7 +1688,7 @@ declare namespace web3n.files {
 		newItemName?: string;
 	}
 
-	interface OptionsToAdoptAllRemoteItems {
+	interface OptionsToMergeFolderVersions {
 		/**
 		 * Folder's local version. If not given, current local version is used.
 		 */
@@ -1510,125 +1704,4 @@ declare namespace web3n.files {
 		postfixForNameOverlaps?: string;
 	}
 
-	interface FSEvent {
-		path: string;
-	}
-
-	interface FSChangeEvent {
-		path: string;
-		src: 'local'|'sync';
-	}
-
-	interface RemovedEvent extends FSChangeEvent {
-		type: 'removed';
-	}
-
-	interface VersionChangeOnUpload extends FSChangeEvent {
-		type: 'version-change-on-upload';
-		src: 'sync';
-		newVersion: number;
-	}
-
-	type FolderEvent = EntryRemovalEvent | EntryAdditionEvent |
-		EntryRenamingEvent | RemovedEvent | VersionChangeOnUpload;
-
-	interface EntryRemovalEvent extends FSChangeEvent {
-		type: 'entry-removal';
-		name: string;
-		moveLabel?: number;
-		newVersion?: number;
-	}
-
-	interface EntryAdditionEvent extends FSChangeEvent {
-		type: 'entry-addition';
-		entry: ListingEntry;
-		moveLabel?: number;
-		newVersion?: number;
-	}
-
-	interface EntryRenamingEvent extends FSChangeEvent {
-		type: 'entry-renaming';
-		oldName: string;
-		newName: string;
-		newVersion?: number;
-	}
-
-	type FileEvent = FileChangeEvent | RemovedEvent | VersionChangeOnUpload;
-
-	interface FileChangeEvent extends FSChangeEvent {
-		type: 'file-change';
-		newVersion?: number;
-	}
-
-	type RemoteEvent = RemoteVersionArchivalEvent | RemoteArchVerRemovalEvent |
-		RemoteRemovalEvent | RemoteChangeEvent;
-
-	interface RemoteVersionArchivalEvent extends FSEvent {
-		type: 'remote-version-archival';
-		archivedVersion: number;
-		syncStatus: SyncStatus;
-	}
-
-	interface RemoteArchVerRemovalEvent extends FSEvent {
-		type: 'remote-arch-ver-removal';
-		removedArchVer: number;
-		syncStatus: SyncStatus;
-	}
-
-	interface RemoteRemovalEvent extends FSEvent {
-		type: 'remote-removal';
-		syncStatus: SyncStatus;
-	}
-
-	interface RemoteChangeEvent extends FSEvent {
-		type: 'remote-change';
-		newRemoteVersion: number;
-		syncStatus: SyncStatus;
-	}
-
-	type UploadEvent = UploadStartEvent | UploadProgressEvent | UploadDoneEvent;
-
-	interface UploadEventBase extends FSEvent {
-		uploadTaskId: number;
-		localVersion: number;
-		uploadVersion: number;
-	}
-
-	interface UploadStartEvent extends UploadEventBase {
-		type: 'upload-started';
-		totalBytesToUpload: number;
-	}
-
-	interface UploadProgressEvent extends UploadEventBase {
-		type: 'upload-progress';
-		totalBytesToUpload: number;
-		bytesLeftToUpload: number;
-	}
-
-	interface UploadDoneEvent extends UploadEventBase {
-		type: 'upload-done';
-	}
-
-	type DownloadEvent = DownloadStartEvent | DownloadProgressEvent | DownloadDoneEvent;
-
-	interface DownloadEventBase extends FSEvent {
-		downloadTaskId: number;
-		version: number;
-	}
-
-	interface DownloadStartEvent extends DownloadEventBase {
-		type: 'download-started';
-		totalBytesToDownload: number;
-	}
-
-	interface DownloadDoneEvent extends DownloadEventBase {
-		type: 'download-done';
-	}
-
-	interface DownloadProgressEvent extends DownloadEventBase {
-		type: 'download-progress';
-		totalBytesToDownload: number;
-		bytesLeftToDownload: number;
-	}
-
 }

package/build/core-ipc/file.d.ts

@@ -14,6 +14,9 @@ type XAttrsChanges = web3n.files.XAttrsChanges;
 type OptionsToAdopteRemote = web3n.files.OptionsToAdopteRemote;
 type OptionsToUploadLocal = web3n.files.OptionsToUploadLocal;
 type VersionedReadFlags = web3n.files.VersionedReadFlags;
+type FileDiff = web3n.files.FileDiff;
+type CommonDiff = web3n.files.CommonDiff;
+type OptionsToDiffFileVersions = web3n.files.OptionsToDiffFileVersions;
 export declare function makeFileCaller(caller: Caller, fileMsg: FileMsg): File;
 export declare function exposeFileService(file: File, expServices: CoreSideServices): FileMsg;
 export interface FileMsg {
@@ -201,4 +204,48 @@ export declare namespace vListVersions {
     function wrapService(fn: ReadonlyFileVersionedAPI['listVersions']): ExposedFn;
     function makeCaller(caller: Caller, objPath: string[]): ReadonlyFileVersionedAPI['listVersions'];
 }
+export interface CommonDiffMsg {
+    remoteVersion?: Value<number>;
+    currentVersion: number;
+    syncedVersion?: Value<number>;
+    isCurrentLocal: boolean;
+    isRemoteRemoved: boolean;
+    ctime?: DiffTimeStampsMsg;
+    mtime?: DiffTimeStampsMsg;
+    xattrs?: {
+        name: string;
+        addedIn?: Value<'l' | 'r' | 'l&r'>;
+        removedIn?: Value<'l' | 'r'>;
+        changedIn?: Value<'l' | 'r' | 'l&r'>;
+    }[];
+}
+export interface DiffTimeStampsMsg {
+    remote: number;
+    current: number;
+    synced: number;
+}
+export interface FileDiffMsg extends CommonDiffMsg {
+    areContentsSame: boolean;
+    size?: {
+        remote: number;
+        current: number;
+    };
+}
+export declare function commonDiffToMsg(diff: CommonDiff): CommonDiffMsg;
+export declare function commonDiffFromMsg(msg: CommonDiffMsg): CommonDiff;
+export declare function fileDiffToMsg(diff: FileDiff | undefined): FileDiffMsg | undefined;
+export declare function fileDiffFromMsg(msg: FileDiffMsg | undefined): FileDiff | undefined;
+export declare namespace vsDiffCurrentAndRemoteVersions {
+    interface OptionsMsg {
+        remoteVersion?: Value<number>;
+        compareContentIfSameMTime?: Value<boolean>;
+    }
+    function optsFromMsg(opts: OptionsMsg | undefined): OptionsToDiffFileVersions | undefined;
+    function optsToMsg(opts: OptionsToDiffFileVersions | undefined): OptionsMsg | undefined;
+    const replyType: ProtoType<{
+        diff?: FileDiffMsg;
+    }>;
+    function wrapService(fn: ReadonlyFileSyncAPI['diffCurrentAndRemoteVersions']): ExposedFn;
+    function makeCaller(caller: Caller, objPath: string[]): ReadonlyFileSyncAPI['diffCurrentAndRemoteVersions'];
+}
 export {};