Skip to content
Experience Quality Coding for AI

Chapter 8: Advanced Debugging System

The Timeline library provides an advanced debugging system that is also extremely effective for AI coding.

1. Activation and Control: Flexible Debug Mode Management

Section titled “1. Activation and Control: Flexible Debug Mode Management”

Debug mode can be flexibly activated in various environments.

  • Automatic Detection Based on Environment:
    • Node.js: Activated when the environment variable process.env.NODE_ENV === 'development'.
    • Browser: Automatically enabled when a development environment is inferred, such as through a URL parameter (?debug=true), a localStorage flag (timeline-debug: 'true'), or access from localhost or specific IP addresses.
  • Manual Control via API:
    • Using the DebugControl object, you can change persistent settings by calling enable() / disable() from the developer console (requires a reload).
    • enableTemporary() can be used to temporarily activate it for the current session without a reload.

2. Information Gathering: Complete Recording of All Dependencies

Section titled “2. Information Gathering: Complete Recording of All Dependencies”

When debug mode is enabled, DependencyCore records its internal operations in detail.

  • Illusion: Groups of dependencies generated by bind, using, etc., are recorded as DebugInfo. This includes their own ID, an array of their dependencyIds, creation time, and a parentIllusion ID to construct the tree structure.
  • Dependency: Individual dependencies are recorded as DependencyDebugInfo. This includes detailed metadata such as their own ID, sourceId (from which timeline), targetId (to which timeline), the illusionId they belong to, the presence of a cleanup function (hasCleanup), and creation time.

3. Runtime Protection: Run-time Guard Against Circular References

Section titled “3. Runtime Protection: Run-time Guard Against Circular References”

When debug mode is enabled, the define function uses a Set called currentlyUpdating to monitor whether a data update has entered an infinite loop. If the same timeline is about to be updated again during the same update process, it is identified as a circular reference, a warning is output to the console, and the process is interrupted.

4. Developer API: Visualization and Manipulation of Information

Section titled “4. Developer API: Visualization and Manipulation of Information”

The collected information can be accessed and visualized through the DebugUtils object.

  • getInfo(): You can get the raw data arrays of all recorded illusions and dependencies, as well as their total counts (totalIllusions, totalDependencies), as an object.
  • printTree(): This is the most powerful feature of the debugging system.
    • Display of Tree Structure: Based on the collected parentIllusion information, it reconstructs the parent-child relationships of the illusions. Then, using console.group, it displays a hierarchically indented dependency tree on the console.
    • Detailed Information: For each illusion in the tree, its ID, parent ID, creation time, and the number of dependencies it contains are displayed. Below that, for each of its dependencies, details such as its ID, the source and target timeline IDs, and the presence of a cleanup function are shown.

These features allow developers to deeply understand the internal state of the system and efficiently diagnose complex problems.