pd_log 0.8.2

Cross-platform Flutter logging with pure Dart; buffered file writes; no platform channels.

0.8.2 — Pub.dev Compliance Fix (Patch)

Release date: 2026-07-06

Improvements

• Translated all Chinese content in CHANGELOG.md to English for pub.dev compliance.
• Verified homepage and repository URLs are accessible via HEAD requests.
• Fixed test dependency version conflict by downgrading test from ^1.25.2 to ^1.24.0 for Flutter 3.10.x compatibility.
• Updated project Flutter version in .fvmrc to 3.10.6 for SDK compatibility.
• Code quality: dart analyze zero issues; fvm flutter test all passed (9 tests).

Compatibility

• No breaking changes; documentation-only patch upgrade for pub.dev compliance.

---

0.8.1 — Documentation & Pub.dev Compliance (Patch)

Release date: 2026-06-17

Improvements

• Added comprehensive dartdoc comments for all classes, enums, and functions across the codebase.
• Converted description in pubspec.yaml to English for pub.dev compliance.
• Converted README.md to English with platform support table and updated version references.
• Fixed dangling library doc comments by adding proper library pd_log; directive.
• Fixed conditional export comments to English in file_watchers.dart.
• Code quality: fvm flutter analyze zero issues; dart format . unified style; fvm flutter test all passed.
• Generated latest API documentation: dart doc.

Compatibility

• No breaking changes; documentation-only patch upgrade.

---

0.8.0 — Async JSON Pretty-Print & Documentation Comments (Minor)

Release date: 2025-12-16

New Features

• Added LogUtils.formatJsonAsync (Isolate execution), providing an async channel for JSON pretty-printing of complex Maps/objects to avoid main isolate blocking.
• Added PDLog.formatJsonAsync and PDLog.formatedAsync, exposing async formatting and printing capabilities at the plugin API level (Web automatically falls back to synchronous implementation).

Improvements

• Added documentation comments for PDLog.formated, recommending async version for large objects/high-frequency scenarios; added complete behavior descriptions for async APIs.
• Code quality: dart analyze, dart format, and flutter test all passed.
• Generated latest API documentation: dart doc.
• Updated README current version and installation snippet to ^0.8.0.

Compatibility

• No breaking changes; minor version upgrade with new capabilities. Recommended to upgrade to 0.8.0 for smoother pretty-printing and improved documentation.

---

0.7.3 — Documentation & Release Process Alignment (Patch)

Release date: 2025-10-24

Improvements

• Unified documentation terminology to "Pure Dart" and completed website documentation revisions (buffer flush & event listening, file storage & rotation, metadata & history, etc.).
• Code quality: dart analyze zero issues; dart format . unified style; flutter test all passed.
• Generated API documentation (dart doc), local preview.

Compatibility

• No breaking changes; recommended to upgrade to 0.7.3 for latest documentation and release process verification.

---

0.7.2 — Documentation Comments Enhancement & Technical Docs Sync (Patch)

Release date: 2025-10-20

Improvements

• Enhanced source code documentation comments covering: log_ledger_io.dart/log_ledger_web.dart, dart_file_logger.dart, file_watchers_web.dart, platform_service_io.dart/platform_service_web.dart, list_options.dart, log_query.dart.
• Documentation module sync:
  • doc/query_and_pagination.md: Removed non-existent SortBy.size, added fallback semantics for SortBy.time (prioritizes modifiedMs, falls back to parsed year/month/day).
  • doc/web_platform.md: Clarified Web file watching as no-op (FileWatchManager), platform service version and path behavior (userAgent / logRootPath == null / empty event stream).
  • doc/metadata_and_history.md: Strengthened snapshot atomic write strategy description (temporary file + rename), added immediate creation events and listSummary filtering/sorting/pagination capability examples.
• Engineering quality: flutter analyze zero issues.

Compatibility

• No breaking changes; recommended to upgrade to 0.7.2 for more complete documentation and source code comments.

---

0.7.1 — Flutter SDK 3.10.6 Compatibility Update

Improvements

• Updated Dart SDK version constraint to >=2.19.6 <4.0.0, supporting Dart 3.x
• Upgraded dependency: plugin_platform_interface to 2.1.8
• Upgraded lints dev dependency to 2.1.1
• Fixed deprecated API usage in test code, replaced setMockMethodCallHandler with TestDefaultBinaryMessengerBinding

0.7.0 — ANSI Toggle & Console/File Color Separation (Minor)

Release date: 2025-10-16

New Features

• Added global configuration option: PDLogConfig.ansiEnabled (default false). Controls whether console/platform output wraps ANSI colors; file writes always use plain text.

Improvements

• Separated coloring behavior between console and file output:
  • Console output (Dart/platform) retains ANSI escape codes when ansiEnabled: false;
  • File writes never contain ANSI escape codes (plain text), facilitating subsequent analysis and archiving.
• Documentation sync: Updated README.md, doc/configuration.md, doc/styling_and_formatting.md with explanations and examples; corrected default value to true.
• Engineering quality: flutter analyze zero issues, unified formatting (dart format .), all unit tests passed (11 items).

Compatibility

• No breaking changes; recommended to upgrade to 0.7.0 for more flexible console coloring and consistent file plain text output.

0.6.2 — Release Verification & Documentation Sync (Patch)

Release date: 2025-10-16

Improvements

• Static analysis and formatting: Fixed/cleaned up hints, unified code style (dart format .), flutter analyze zero issues.
• Unit tests: All passed (11 items).
• Version upgrade: pubspec.yaml upgraded to 0.6.2, README dependency snippet synced to ^0.6.2.
• Documentation alignment: Added README toggle descriptions and Web limitations, unified "platform-side/local file writing (Dart-managed)" terminology.

Compatibility

• No breaking changes; recommended to upgrade for improved documentation and release verification.

0.6.1 — Release Preparation & Documentation Sync (Patch)

Release date: 2025-10-15

Improvements

• Unified code quality: flutter analyze zero issues, flutter test all passed.
• Upgraded version to 0.6.1 and updated README and getting started documentation installation snippets to ^0.6.1.
• Top-level documentation directory aligned with pub layout conventions: using doc/ (keeping documentation website structure unchanged).
• Added .pubignore to exclude example file reading helper source files, eliminating release warnings.
• Terminology and comments unified: Changed "native write/native-side" to "platform-side/local file writing (Dart-managed)", covering lib/ source code and API documentation comments.
• Clarified flush responsibility: PDLog.flushNativeLogs() flushes Dart writer; platform-side methods retained as placeholders for API consistency.
• README adjustment: Removed useNative parameter description, unified console output control via useConsole; retained nativeFileLoggingEnabled description; marked Web does not perform local file writing.
• pubspec.yaml description updated to Dart-managed buffered file writing and platform console printing.

Compatibility

• No breaking changes; recommended upgrade for more standard package layout and documentation.

0.6.0 — Query API Enhancement & File Metadata Derivation (Minor)

Release date: 2025-10-13

New Features

• Introduced unified query options ListOptions, supporting:
  • Sorting: SortBy.time (prioritizes modifiedMs, falls back to parsed year/month/day), SortBy.name;
  • Direction: SortDirection.asc | desc;
  • Pagination: pageSize and page.
• Integrated ListOptions into public query APIs:
  • PDLog.listLogFiles({ListOptions? options})
  • PDLog.listLogFilesByYear(int year, {ListOptions? options})
  • PDLog.listLogFilesByYearMonth(int year, int month, {ListOptions? options})
• Added derived read-only fields to PDLogFile: year/month/day, parsed from normalized path .../<yyyy>/<MM>/<dd>.log; returns null when last segment is not dd.log.

Improvements

• Added LogQuery.applyOptions, unified sorting and pagination logic; fixed descending implementation to be compatible with Dart List API (using list.reversed.toList()).
• Improved documentation comments and README examples, enhancing API discoverability and developer experience.

Engineering

• Static analysis passed (flutter analyze).
• Unified formatting (dart format .).
• Unit tests passed (added parsing and sorting/pagination tests).

0.5.1 — Documentation Enhancement & Release (Patch)

Release date: 2025-10-11

Improvements

• Added and improved Dart source code documentation comments (pd_log.dart, src/log_query.dart, src/log_utils.dart).
• README added "API Documentation Comments" section, explaining documentation can be viewed via IDE/Dartdoc.

Release

• Upgraded pubspec.yaml version to 0.5.1 for releasing the above documentation updates.

0.5.0 — Log Path Structure Upgrade (Minor)

Release date: 2025-10-11

Change Summary

• Unified raw log file path structure to /<year>/<month>/<day>.log, final example: pd_log/2025/01/19.log.
• Affected platforms: Android (Kotlin), iOS/macOS (Swift), Windows (C++), Linux (C++/glib).

Compatibility & Impact

• External Dart API remains unchanged: listLogFiles() still recursively enumerates, listYearFolders() only lists first-level year directories.
• Existing log rotation strategy (based on modifiedMs) is unaffected.
• Historical files with /<year>/<yyyy-MM-dd>.log structure can still be managed through recursive enumeration and deletion interfaces; migration can be done as needed for unified structure.

Documentation

• Updated README "File Organization" and FAQ sections, explaining new month subdirectories and day file naming.
• Installation version updated to ^0.5.0.

Upgrade Recommendation

• Recommended to upgrade to 0.5.0 for clearer directory organization (year/month/day). If external scripts depend on the old path pattern, please adjust parsing rules accordingly.

New Dart API

• Added date/year/month query helper methods for quickly locating log files at Dart layer:
  • PDLog.logFilePathIfExists(DateTime date): Checks if .log file exists for specified date; returns absolute path if exists, empty string otherwise.
  • PDLog.listLogFilesByYear(int year): Lists all log files under specified year directory.
  • PDLog.listLogFilesByYearMonth(int year, int month): Lists all log files under specified year/month directory.

Internal Refactoring

• Extracted common path and filtering logic to lib/src/log_query.dart (LogQuery utility class), unified path separator handling, root path normalization, and prefix filtering, reducing implementation complexity of PDLog class.

Documentation

• Updated README "Common API" and "Query Examples (by Date/Year/Month)" sections, adding descriptions and example code for the above new query capabilities.
• Improved Dart documentation comments for source code (pd_log.dart, src/log_query.dart, src/log_utils.dart, etc.), enhancing API readability and consistency.

0.4.0 — Log Rotation Strategy (Minor Feature)

Release date: 2025-10-10

New Features

• Added log file rotation strategy (fully implemented at Dart layer, avoiding multi-platform duplicate logic):
  • Supports keeping recent N cycles by day/month/year, automatically deleting the rest;
  • Added configuration options: PDLogConfig.logRetentionStrategy and PDLogConfig.logRetentionCount;
  • PDLog.updateConfigure supports the above configurations and automatically executes cleanup after update;
  • Added public API: PDLog.enforceRotation() for manual cleanup triggering at any time.

Documentation

• Added rotation strategy section and examples to README.

Compatibility

• Minor version update (feature addition), no breaking external API changes; recommended to upgrade to 0.4.0 for automatic cleanup and unified configuration capabilities.

0.3.1 — Comprehensive Documentation Enhancement & Release Process Verification (Patch)

Release date: 2025-10-09

Improvements

• Added and unified cross-platform implementation documentation comments (Dart layer, iOS/macOS, Windows, Linux, Web), covering buffering strategy, file path conventions, MethodChannel interaction, and log level filtering rules.
• Added minimum level filtering description for LogLevel enum, clarifying enum order and collaboration with fileLoggingMinLevel.
• Enhanced PDLog and PDLogConfig field documentation, explaining file logging behavior and platform limitations (Web does not support file writing).

Engineering

• Passed dart analyze comprehensive static analysis, no issues.
• Unified code formatting (dart format .).
• All unit tests passed (flutter test).
• Generated local API documentation (dart doc).

Compatibility

• No breaking changes, recommended to upgrade to 0.3.1 for more complete documentation and more robust release process verification.

0.3.0 — JSON Pretty-Print & Output Readability Optimization (Minor)

Release date: 2025-10-08

New Features/Improvements

• Added JSON pretty-print: PDLog.formated(Object? message) uses JsonEncoder.withIndent and custom recursive normalization logic, supporting line breaks, indentation, and valid double-quote output; compatible with non-string Map keys (converted to strings), Iterable, DateTime (ISO8601), and objects with toJson().
• Optimized log concatenation readability: Introduced intermediate variable wantCaller in log_utils.dart and implemented segment filtering + space concatenation ([tsPart, callerPart, msgText].where(...).join(' ')), avoiding extra spaces when timestamp/caller information is not displayed.
• Per-line ANSI style preservation: Applied styles line by line in multi-line messages to ensure colors/styles are not lost after line breaks.

Compatibility

• No breaking external API changes; PDLog.formated output is more readable and valid JSON. When Map keys are non-string types, they are unified to strings according to JSON specification (e.g., 1 → "1"). If key type semantics need to be preserved, custom non-JSON format or [{key, keyType, value}] structure can be used on the business side.

Upgrade Recommendation

• Recommended to upgrade to 0.3.0 for better JSON readability and log cleanliness. If parsers depend on the old output format, please verify and adjust to accommodate the new space concatenation and pretty-print output.

0.2.2 — Multi-line Style Fix & Release Process Improvement (Patch)

Release date: 2025-10-07

Fixes

• Fixed issue where subsequent lines did not inherit ANSI styles when log messages contained newline characters; changed to wrapping style sequences line by line to ensure consistent colors/styles per line (lib/src/log_utils.dart).

Improvements

• Unified code formatting and passed static analysis and unit tests; updated README installation version to ^0.2.2.

Compatibility

• No breaking changes, recommended to upgrade to 0.2.2 for better log readability.

0.2.1 — Caller Information Fix & Stability Improvement (Patch)

Release date: 2025-10-06

Fixes

• Used package:stack_trace to unify call stack parsing (Trace/Frame), stably obtaining caller's function name, file, and line number across multiple platforms.
• Corrected filtering rules to avoid mistakenly treating example business packages (e.g., pd_log_example) as internal packages and skipping them, which caused caller information not to be displayed.

Improvements

• Added dependency: stack_trace, improving cross-platform stack parsing compatibility and maintainability.
• Continued maintaining original log output format and style system, avoiding external API breakage; this is a behavior fix.

Compatibility

• No breaking API changes, recommended to upgrade to 0.2.1 for more accurate caller information display.

0.2.0 — Style System Unification & API Migration (Breaking)

Release date: 2025-10-05

Change Summary

• Unified log coloring to style system: Added LogStyleConfig (foreground/background/text style), with default mapping kDefaultLogStyles.
• Removed colorCode parameter from PDLog.out; deleted LogLevelExt.ansiColorCode mapping.
• Coloring logic changed to priority: call-level style → global PDLogConfig.logStyles[level] → no color.

Migration Guide (Breaking Changes)

• Old code: PDLog.out('msg', colorCode: 34) → New code:

  PDLog.out('msg', level: LogLevel.info, style: LogStyleConfig(foreground: 34));
  

• Old reference: LogLevel.info.ansiColorCode → Use PDLogConfig.logStyles[LogLevel.info] or directly construct LogStyleConfig.
• For background and text styles (bold/italic/underline, etc.), use LogStyleConfig(background: 47, styles: [1, 3, 4]).

Documentation

• Updated README examples to style usage; added ANSI color, background, and style references.
• Regenerated API documentation, ensuring Dartdoc links (e.g., LogStyleConfig.ansiStartSequence) are navigable.

0.1.3 — Documentation Comments Enhancement & Internal Refactoring

Release date: 2025-10-04

Improvements

• Improved Dart-side documentation comment quality: Added comprehensive comments for PDLog, platform interfaces and implementations, configuration and level enums, file metadata, etc., optimizing reading experience and API discoverability.
• Extracted core logging logic to lib/src/log_utils.dart, improving maintainability; migrated ANSI color mapping to LogLevel extension for reuse.
• Cleaned up unreasonable inline comments and unused imports, unified style.

Compatibility

• No breaking changes, maintaining external API stability; recommended to upgrade to 0.1.3 for better documentation and internal implementation.

0.1.2 — Documentation & Metadata Update

Release date: 2025-10-03

Improvements

• Updated README.md installation example version to ^0.1.2, synced latest release information.
• Updated iOS/macOS Podspec author and homepage to real information (Pedro Pei / [e-mail] / Gitee repository).
• Unified Android package ID and namespace to me.pedro.pei.pd_log (continuing 0.1.1 fix, clarified in examples and documentation).

0.1.1 — Android Build Fix

Release date: 2025-10-02

Fixes

• Added namespace "com.example.pd_log" to Android module, resolving build errors in AGP 8+ environment (Namespace not specified).
• Version number upgraded to 0.1.1, semantic patch release.

0.1.0 — First Public Beta Version

Release date: 2025-10-01

New Features

• Provides cross-platform unified logging API: PDLog.v/d/i/w/e, tag and timestamp support, optional caller information.
• Native file logging buffering: Supports time-based and buffer threshold-triggered flushing, reducing frequent disk writes.
• Log file management: Enumerate log files, statistics total size, delete single or all logs.
• Platform support: Android / iOS / macOS / Windows / Linux / Web.

Improvements

• Dart-side string concatenation optimization, improving readability and minor performance (lib/pd_log.dart).
• iOS/macOS native concurrency fix: Removed same-queue synchronous blocking risk, failure fallback and retry logic more robust.
• Linux native scheduling fix: Avoided potential deadlock caused by repeated calls while holding lock.

Documentation

• Added README, with complete feature descriptions, installation guide, usage methods, and example code.
• Added MIT LICENSE.