feat: sha-2 hash functions; refactoring

Breaking Changes

Author: rafamizes

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Dart Package Versioning](https://dart.dev/tools/pub
 
 ## [Unreleased]
 
+### Added
+
+- file "func.dart" with the definition of the functional interfaces.
+- cryptographic package with hash functions sha224, sha256, sha384, sha512,
+  along with their related Hmac function (Hash-based message authentication
+  code)
+- tabular text of ordinary text and data. The data can be represented with
+  binary, octal, decimal, or hexadecimal notation.
+- radix package: a set of classes for converting numeric data into its textual
+  representation in a given radix (numeric base).
+- bit package: a set of classes for bit-related operations.
+- several benchmarks comparing Dartoos to the Dart sdk or other third-party
+  packages like _Crypto_.
+
+### Changed
+
+- No class extends FutureWrap any more — **BREAKING CHANGE**.
+- A general reorganization of the package directory structures.
+
+### Removed
+
+- FutureWrap — **BREAKING CHANGE**.
+
 ## [0.2.0] - 2021-10-15
 
 ### Added

README.md

@@ -33,8 +33,7 @@ This project is heavily inspired by Java
 
 - No external dependencies.
 - Object-Oriented mindset: each concept is implemented by an **immutable** class.
-- For easier composability and integration with the undelying Dart's sdk, most
-  of the classes are instances of Future.
+- Straightforward integration with the underlying Dart sdk.
 
 ## Getting started
 

example/.gitignore

@@ -0,0 +1,6 @@
+# Files and directories created by pub.
+.dart_tool/
+.packages
+
+# Conventional directory for build output.
+build/

example/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+- Initial version.

example/README.md

@@ -0,0 +1,20 @@
+# Dartoos Showcase
+
+How to use Dartoos effectively.
+
+## Getting Started
+
+From the root directory of this project, enter the following commands:
+
+```shell
+  cd example/
+  dart run  radix/hex_of_bytes_benchmark.dart
+```
+
+This launchs the benchmark of the `HexOfBytes` class, which in turn converts an
+array of bytes to its hexadecimal text representation. The end result is a small
+report that compares the performance of a typical Dart implementation of such a
+conversion (bytes to hexadecimal) with the performance of the conversion
+provided by the Dartoos package.
+
+Likewise, you can issue similar commands to launch other benchmarks programs.

example/analysis_options.yaml

@@ -0,0 +1,23 @@
+include: package:lint/analysis_options_package.yaml
+analyzer:
+  strong-mode:
+    # A value of false ensures that the type inference engine never implicitly casts
+    # from dynamic to a more specific type.
+    implicit-casts: false
+    # A value of false ensures that the type inference engine never chooses the
+    # dynamic type when it can’t determine a static type.
+    # implicit-dynamic: false
+    implicit-dynamic: false
+linter:
+  rules:
+    # Make constructors the first thing in every class
+    sort_constructors_first: true
+    # Good packages document everything
+    public_member_api_docs: true
+    # Always await.
+    unawaited_futures: true
+    always_declare_return_types: true
+    cancel_subscriptions: true
+    close_sinks: true
+    only_throw_errors: true
+    package_api_docs: true

example/base64_benchmark.dart

@@ -0,0 +1,45 @@
+// ignore_for_file: avoid_print
+
+import 'package:crypto/crypto.dart' as crypto;
+import 'package:dartoos/dartoos.dart';
+
+import '../../utils/perf_gain.dart';
+
+/// Dartoos Hmac Sha256 vs. Dart's built-in
+///
+/// Running:
+/// ```dart /example/crypto/hash/hmac_sha256_benchmark.dart```
+///
+/// or
+///
+/// Compile to 'jit'.
+/// ```dart compile jit-snapshot example/crypto/hash/hmac_sha256_benchmark.dart```
+/// ```dart /example/crypto/hash/hmac_sha256_benchemark.jit```
+void main() {
+  print("Dartoos HMAC-SHA256 vs. Cryptos HMAC-SHA256...");
+  const len = 25000000;
+  const alphabet =
+      'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  final data = BytesOf.text(Rand(len, alphabet)).value;
+  final key = BytesOf.utf8('Dartoos vs Crypto').value;
+  print('\nLength of the data to be hashed: ${data.lengthInBytes} bytes.');
+
+  print('\n--- Hashing elapsed times ---');
+  final watch = Stopwatch()..start();
+  final cryptoHmac = crypto.Hmac(crypto.sha256, key).convert(data).toString();
+  final cryptoHashTime = watch.elapsedMicroseconds / 1000;
+  watch.stop();
+  print('Crypto hashing time.......: $cryptoHashTime milliseconds');
+  print('Crypto digest value.......: $cryptoHmac');
+  watch.reset();
+
+  watch.start();
+  final dartoosHmac = HexHmac.sha256(key).value(data);
+  final dartoosHashTime = watch.elapsedMicroseconds / 1000;
+  watch.stop();
+  print('Dartoos hashing time......: $dartoosHashTime milliseconds');
+  print('Dartoos digest value......: $dartoosHmac');
+  const perf = PerfGain();
+  print('Performance ratio.........: ${perf(cryptoHashTime, dartoosHashTime)}');
+  print('Are the generated digests the same? ${dartoosHmac == cryptoHmac}');
+}

example/crypto/hash/hmac_sha256_benchmark.dart

@@ -0,0 +1,46 @@
+// ignore_for_file: avoid_print
+
+import 'package:crypto/crypto.dart' as crypto;
+import 'package:dartoos/dartoos.dart';
+
+import '../../utils/perf_gain.dart';
+
+/// Dartoos sha256 vs. Dart's built-in
+///
+/// Running:
+/// ```dart /example/crypto/hash/sha256_benchmark.dart```
+///
+/// or
+///
+/// Compile to 'jit'.
+/// ```dart compile jit-snapshot example/crypto/hash/sha256_benchmark.dart```
+/// ```dart /example/crypto/hash/sha256_benchemark.jit```
+void main() {
+  print("Dartoos sha256 vs. Cryptos sha256...");
+
+  const len = 25000000;
+  const alphabet =
+      'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  final data = BytesOf.text(Rand(len, alphabet)).value;
+  print('\nLength of the data to be hashed: ${data.lengthInBytes} bytes.');
+
+  print('\n--- Hashing elapsed times ---');
+  final watch = Stopwatch()..start();
+  final cryptoDigest = crypto.sha256.convert(data).toString();
+  crypto.sha256.blockSize;
+  final cryptoHashTime = watch.elapsedMicroseconds / 1000;
+  watch.stop();
+  print('Crypto hashing time.......: $cryptoHashTime milliseconds');
+  print('Crypto digest value.......: $cryptoDigest');
+  watch.reset();
+
+  watch.start();
+  final dartoosDigest = hexSha256(data);
+  final dartoosHashTime = watch.elapsedMicroseconds / 1000;
+  watch.stop();
+  print('Dartoos hashing time......: $dartoosHashTime milliseconds');
+  print('Dartoos digest value......: $dartoosDigest');
+  const perf = PerfGain();
+  print('Performance ratio.........: ${perf(cryptoHashTime, dartoosHashTime)}');
+  print('Are the generated digests the same? ${dartoosDigest == cryptoDigest}');
+}

example/crypto/hash/sha256_benchmark.dart

@@ -0,0 +1,45 @@
+// ignore_for_file: avoid_print
+
+import 'package:crypto/crypto.dart' as crypto;
+import 'package:dartoos/dartoos.dart';
+
+import '../../utils/perf_gain.dart';
+
+/// Dartoos sha512 vs. Dart's built-in
+///
+/// Running:
+/// ```dart /example/crypto/hash/sha512_benchmark.dart```
+///
+/// or
+///
+/// Compile to 'jit'.
+/// ```dart compile jit-snapshot example/crypto/hash/sha512_benchmark.dart```
+/// ```dart /example/crypto/hash/sha512_benchemark.jit```
+void main() {
+  print("Dartoos sha512 vs. Crypto sha512...");
+
+  const len = 25000000;
+  const alphabet =
+      'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  final data = BytesOf.text(Rand(len, alphabet)).value;
+  print('\nLength of the data to be hashed: ${data.lengthInBytes} bytes.');
+
+  print('\n--- SHA-512 — Elapsed times for hasing ---');
+  final watch = Stopwatch()..start();
+  final cryptoDigest = crypto.sha512.convert(data).toString();
+  final cryptoHashTime = watch.elapsedMicroseconds / 1000;
+  watch.stop();
+  print('Crypto hashing time.......: $cryptoHashTime milliseconds');
+  print('Crypto digest value.......: $cryptoDigest');
+  watch.reset();
+
+  watch.start();
+  final dartoosDigest = hexSha512(data);
+  final dartoosHashTime = watch.elapsedMicroseconds / 1000;
+  watch.stop();
+  print('Dartoos hashing time......: $dartoosHashTime milliseconds');
+  print('Dartoos digest value......: $dartoosDigest');
+  const perf = PerfGain();
+  print('Performance ratio.........: ${perf(cryptoHashTime, dartoosHashTime)}');
+  print('Are the generated digests the same? ${dartoosDigest == cryptoDigest}');
+}

example/crypto/hash/sha512_benchmark.dart

@@ -0,0 +1,92 @@
+// ignore_for_file: avoid_print
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:dartoos/dartoos.dart';
+import 'package:dartoos/src/encoding/base64/base64_enc.dart';
+
+import '../utils/perf_gain.dart';
+
+/// Dartoos base64-encoder/decoder vs. Dart's built-in base64-encoder/decoder.
+///
+/// Running:
+/// ```shell
+///   dart run example/encoding/base64_benchmark.dart
+/// ```
+///
+/// or
+///
+/// Compile to 'jit'.
+/// ```shell
+///   dart compile jit-snapshot example/encoding/base64_benchmark.dart
+///   dart run /example/encoding/base64_benchmark.jit
+/// ```
+void main() {
+  print("Dartoos base64 vs. Dart's built-in base64...");
+
+  const len = 50000000;
+  const alphabet =
+      'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  final bytes = BytesOf.text(Rand(len, alphabet)).value;
+  print('\nLength of the data to be encoded: ${bytes.length} bytes.');
+
+  print('\n--- Encoding elapsed times ---');
+  final watch = Stopwatch()..start();
+  final dartEnc = base64Encode(bytes);
+  final dartEncTime = watch.elapsedMicroseconds / 1000;
+  print('Dart base64-encoding......: $dartEncTime milliseconds');
+  watch.stop();
+  watch.reset();
+
+  watch.start();
+  const dartoosBase64Enc = Base64Enc();
+  final dartoosEnc = dartoosBase64Enc(bytes);
+  final dartoosEncTime = watch.elapsedMicroseconds / 1000;
+  print('Dartoos base64-encoding...: $dartoosEncTime milliseconds');
+  watch.stop();
+  watch.reset();
+  const perf = PerfGain();
+  print('Encoding Performance......: ${perf(dartEncTime, dartoosEncTime)}');
+
+  print('\n--- Decoding elapsed times ---');
+  watch.start();
+  final dartDec = base64Decode(dartEnc);
+  final dartDecTime = watch.elapsedMicroseconds / 1000;
+  print('Dart base64-decoding......: $dartDecTime milliseconds');
+  watch.stop();
+  watch.reset();
+
+  watch.start();
+  const dartoosDecoder = Base64Dec();
+  final dartoosDec = dartoosDecoder(dartoosEnc);
+  final dartoosDecTime = watch.elapsedMicroseconds / 1000;
+  print('Dartoos base64-decoding...: $dartoosDecTime milliseconds');
+  watch.stop();
+  watch.reset();
+  print('Decoding Performance......: ${perf(dartDecTime, dartoosDecTime)}');
+
+  print('\n--- Encoding/decoding results comparison ---');
+  print('dartEncoded == dartoosEncoded? ${dartEnc == dartoosEnc}');
+  print('dartDecoded == dartoosDecoded? ${bytesEqual(dartDec, dartoosDec)}');
+}
+
+/// Checks for the equality between [first] and [second].
+bool bytesEqual(Uint8List first, Uint8List second) {
+  if (first.length != second.length) return false;
+  final length = first.length;
+  int i = 0;
+  while ((i < length) && (first[i] == second[i])) {
+    ++i;
+  }
+  return i == length;
+}
+
+/// Returns a formatted string describing the performance gain ('+', positive
+/// values) or loss ('-', negative values).
+///
+/// Examples: +12% for a performance gain; -5.5% for a performance loss.
+// String perfGain(double dartTime, double dartoosTime) {
+// final perc = ((dartTime / dartoosTime) * 100) - 100;
+// final sign = perc > 0 ? '+' : '';
+// return "$sign${perc.toStringAsFixed(2)}% ('+' gain; '-' loss)";
+// }