file_hasher
A utility for hashing one or more files with the XXH3 hashing algorithm.
file_hasher relies on the xxh3 package.
About
file_hasher works by splitting files into chunks, individually hashing
each chunk with the XXH3 hashing
algorithm, then combining each hash with the existing digest with the
bit-wise exclusive-or operator (^), and returning the result.
The [FileHasher] utility class provides a method to hash individual files, [hash], as well as a method to hash multiple files, [smash], and their synchronous variants, [hashSync] and [smashSync].
Usage
import 'package:file_hasher/file_hasher.dart';
hash & hashSync
The [hash] and [hashSync] methods hash the contents of a single file.
[hash] streams the contents of a file, while [hashSync] reads the file synchronously then processes the file data.
final file = File.fromUri(Uri.file('path/to/file'));
// Asynchronously hash the file.
print(await FileHasher.hash(file));
// Synchronously hash the file.
print(FileHasher.hashSync(file));
smash & smashSync
The [smash] and [smashSync] methods hash the contents of multiple files in the order they’re listed.
[smash] streams the contents of the files, while [smashSync] reads the files synchronously then processes the file data.
final files = <File>[
File.fromUri(Uri.file('path/to/file1')),
File.fromUri(Uri.file('path/to/file2')),
File.fromUri(Uri.file('path/to/file3')),
];
// Asynchronously hash the files.
print(await FileHasher.smash(files));
// Synchronously hash the files.
print(FileHasher.smashSync(files));
File extension methods
file_hasher extends the [File] object from the dart:io package with two
methods: [xxh3] and [xxh3Sync]; which call [FileHasher]’s [hash] and [hashSync]
methods respectively.
// Asynchronously hash the file.
print(await file.xxh3());
// Synchronously hash the files.
print(file.xxh3Sync());
Parameters
Each of the methods provided by [FileHasher], as well as the [File] extension methods, have 3 optional parameters: [chunkSize], [seed], and [secret].
See below for details.
final hash = await FileHasher.hash(
file,
chunkSize: 500,
seed: 20220713,
secret: mySecretUint8List,
);
chunkSize
[chunkSize] sets the number of bytes to include in each chunk of data being hashed; changing the [chunkSize] will result in different hashes being returned for any files containing more bytes than the [chunkSize].
[chunkSize] defaults to 2500.
seed
A [seed] can be provided as an [int] to randomize the hash function.
[seed] defaults to 0.
secret
An optional [secret] can also be provided as a [Uint8List] to randomize the hash function.
If provided, the [secret] must be at least 136 bytes.
Note: Per XXH3 and the xxh3 package, the secret must look like a bunch of random bytes as the quality of the secret impacts the dispersion of the hash algorithm. “Trivial” or structured data such as repeated sequences or a text document should be avoided.
Note: [Uint8List] can be imported from the dart:typed_data package
and can be constructed from a list of [int]s.
