timsoftdz_core 1.0.1

Enterprise-grade core library for Dart & Flutter — Result pattern, unified exception hierarchy, structured logging with pipelines, interceptor-based HTTP client, contract-driven key-value storage, Uni [...]

Changelog

All notable changes to timsoftdz_core are documented in this file.
Format follows Keep a Changelog;
versioning follows Semantic Versioning.

---

1.0.0 — 2026-04-27

This is the first production-grade release of timsoftdz_core.
The 0.x series was exploratory; 1.0 ships a stable, documented, fully-tested public API with pub.dev 160+ score target.

⚠️ Breaking Changes (from 0.x)

See MIGRATION.md for a step-by-step guide.

Area	0.x	1.0
TimLogger	debug/info/warning/error/success	+trace, +fatal levels added
LogLevel	5 levels	7 levels (trace…fatal)
RetryPolicy	ExponentialBackoff only	+JitteredExponentialBackoff (default for standard)
StorageEncryptionCodec	encrypt/decrypt	renamed to encode/decode (aliases kept)
TimStorage	partial interface	full contract with getInt, getBool, setInt, setBool, setDouble
AppException	7 subtypes	10 subtypes (+ConflictException, +RateLimitedException, +CancelledException)
Namespace	flat exports	Organised barrel with library timsoftdz_core;

Added

Core

• Result<T> — Sealed union (Success<T> / Failure<T>) with:
  • fold(), mapAsync(), flatMapAsync(), swap(), recover(), recoverWith()
  • Result.guard() (alias for run)
  • FutureResultX<T> — async chain operators: thenMap, thenFlatMap, thenFold, etc.
• ErrorCode — 50+ machine-readable string constants for all error scenarios.
• AppException.fromError() — factory to wrap arbitrary errors.

Exception Hierarchy

• ConflictException — HTTP 409
• RateLimitedException — HTTP 429
• CancelledException — request cancelled via CancelToken

Logging

• LogLevel.trace and LogLevel.fatal (two new levels).
• LogLevel comparison operators (<, <=, >, >=).
• LogEntry.extra — structured key-value metadata map.
• LogEntry.toJson() / toJsonString() / copyWith().
• JsonLogger — newline-delimited JSON output for log pipelines (ELK, Loki).
• FilteredLogger — decorator that applies a LogFilter before forwarding.
• FileLogger (stub) — interface for file-based logging (bring-your-own sink).
• LogFilter abstract class + built-in filters:
  • MinLevelFilter, ExactLevelFilter, TagFilter, MessageContainsFilter
  • AllowAllFilter, BlockAllFilter
  • Compose with &, |, ~ operators.
• ConsoleLogger: lazy message evaluation, trace/fatal support, showTimestamp, showLevel.

Networking

• TimHttpClientContract — abstract interface for full testability.
• CancelToken — cooperative request cancellation; throwIfCancelled().
• JitteredExponentialBackoff — full-jitter strategy (thundering-herd safe).
• RetryPolicy.standard / RetryPolicy.aggressive — preset policies.
• HEAD request support.
• Request / Response / Error interceptor pipeline (onRequest, onResponse, onError).
• TimHttpResponse: isOk, isCreated, isUnauthorized, isNotFound, isServerError, bodyAsMap(), bodyAsList(), bodyAsJson(), equality, toString.

Storage

• CachedStorage — read-through, write-through cache layer with optional TTL.
• StorageEncryptionCodec — plugin interface; encode/decode (replaces encrypt/decrypt).
• Base64StorageCodec — Unicode-safe Base64 obfuscation.
• NoOpStorageCodec — pass-through for testing.
• AlwaysFailStorage — always-failing stub for testing failure paths.
• MemoryStorage.reset() / MemoryStorage.snapshot / MemoryStorage.length.
• TimStorage.getInt(), getBool(), setInt(), setBool(), getDouble() / setDouble().
• Atomic write-then-rename in FileStorage (prevents corruption on crash).
• FileStorage.deleteFile(), fileExists.
• FileStorage.setAll() batches all writes in one flush.

Strings

• toKebabCase() — converts camelCase/PascalCase/snake_case to kebab-case.
• isDigitsOnly, isAlpha, isAlphanumeric predicates.
• removeChars(String chars) — remove all occurrences of given characters.
• countOccurrences(String pattern) — count non-overlapping occurrences.
• initials({int max}) — instance method on String.
• TimStringUtils.pluralise() — i18n-friendly singular/plural helper.
• TimStringUtils.initials() — static version.
• TimStringUtils.similarity() — normalised Levenshtein similarity score (0.0–1.0).
• Unicode-safe reversed / unicodeReversed (handles emoji and surrogate pairs).
• byteSizeUtf8 — accurate UTF-8 byte length.
• Optimised levenshtein() (single-row DP, O(min(a,b)) space).
• Optimised randomAlphanumeric() using dart:math Random.

Validation

• Validator.isIPv6() — full IPv6 address validation.
• Validator.isIBAN() — ISO 13616 IBAN checksum (MOD-97).
• Validator.isSlug(), isHexColor(), isJsonString().
• Validator.isPositiveInt(), isUri().
• Validator.passwordStrengthLabel().
• All regex patterns compiled once as static final.

Changed

• TimLogger — log(LogEntry) now handles all 7 levels.
• ConsoleLogger — lazy message evaluation (zero cost for suppressed levels).
• TimStorage.setAll() — default implementation is fail-fast (stops on first error).
• FileStorage — uses atomic write-then-rename for crash safety.
• RetryPolicy default backoff changed from ConstantBackoff(1s) to ConstantBackoff(1s) (unchanged for default constructor); RetryPolicy.standard uses JitteredExponentialBackoff.
• Minimum SDK raised to >=3.3.0 (pattern matching in switch expressions).
• Dependency test upgraded to ^1.25.0, lints to ^4.0.0.

Fixed

• truncateWords() now correctly handles strings with no spaces.
• maskEmail() edge case where local part has exactly 2 characters.
• levenshtein() edge case when both strings are empty.
• DzPhone.carrier() null-safety for invalid input.

Removed

• TimLogger.log(entry) no longer falls through to warning for unknown levels.
• Old direct logger constructors without minLevel now all default to LogLevel.debug.

---

0.1.0 — 2026-01-15

Initial alpha release.

• Result<T> — Success / Failure with map, flatMap, onSuccess, onFailure.
• AppException hierarchy (7 types).
• TimLogger with 5 levels; ConsoleLogger, SilentLogger, CompositeLogger, TaggedLogger.
• TimHttpClient — GET, POST, PUT, PATCH, DELETE with retry.
• MemoryStorage, FileStorage.
• DateFormatter, RelativeTime (EN/AR/FR).
• String extensions: capitalize, titleCase, slugify, truncate, mask.
• Validator — email, phone, password, URL, NIN, Luhn.
• DzPhone — Algerian phone normaliser.