file_hasher

Description:

file hasher

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';
copied to clipboard
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));
copied to clipboard
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));
copied to clipboard
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());
copied to clipboard
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,
);
copied to clipboard
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.