@panyam/tsappkit 0.7.7 → 0.7.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@panyam/tsappkit",
3
- "version": "0.7.7",
3
+ "version": "0.7.8",
4
4
  "description": "TypeScript application toolkit with component lifecycle management, event system, UI utilities, and documentation site components",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -1,100 +1,47 @@
1
1
  /**
2
- * LCMComponent Interface - Defines multi-phase component initialization
2
+ * A LifeCycle Managed Component: one that a LifecycleController starts in
3
+ * phases, so a component can rely on every other component being set up
4
+ * before it activates.
3
5
  *
4
- * This interface implements a breadth-first lifecycle pattern that eliminates
5
- * initialization order dependencies and race conditions through synchronization barriers.
6
- *
7
- * Lifecycle Phases:
8
- * 1. Construction - Components are created but not initialized
9
- * 2. bindToDOM() - Basic DOM setup, discover child components
10
- * 3. injectDependencies() - Receive references to other components
11
- * 4. activate() - Final setup when all dependencies are ready
12
- *
13
- * Key Benefits:
14
- * - Order Independence: Components can be created in any sequence
15
- * - Async Safety: Each phase waits for all components before proceeding
16
- * - Clear Dependencies: Explicit injection points prevent race conditions
17
- * - Error Isolation: Component failures don't cascade to others
18
- */
19
-
20
- /**
21
- * LCM Component - Short for LifeCycle Managed Component
22
- * enable components to be declared first and their loading be managed by a
23
- * LifecycleController so that we have layered creation, dependency injection and setup
24
- * in a breadth first way.
25
- *
26
- * A key constraint on LCMComponents are that they should not perform any initialization
27
- * in the constructor. This is because a LifecycleController should be used to load/setup
28
- * these components and they will follow a layered approach. Performing these actions in
29
- * the constructor could violate the idempotency guarantees.
6
+ * Keep the constructor to storing its arguments. The controller decides when
7
+ * the real work happens, phase by phase over the whole tree:
8
+ * performLocalInit, then setupDependencies, then activate. deactivate runs
9
+ * when the controller is torn down, leaves first.
10
+ * See https://panyam.github.io/goapplib/guide/components/.
30
11
  */
31
12
  export interface LCMComponent {
32
13
  /**
33
- * Phase 1: The "local" initialization of the component.
34
- *
35
- * In this phase the component initializes itself and returns any children it might
36
- * want initialized as part of the lifecycled loading.
37
- *
38
- * This phase should:
39
- * - Set up basic DOM elements and event listeners
40
- * - Create child components (but don't initialize them) and return them
41
- * - Return array of child components for lifecycle controller discovery
14
+ * Phase 1: set the component itself up, and return its children.
42
15
  *
43
- * This phase must be synchronous and should not:
44
- * - Access other components or external dependencies
45
- * - Perform async operations
46
- * - Emit events or notifications
47
- *
48
- * @returns Array of child components to be managed by lifecycle controller
16
+ * Bind to the DOM and create child components here, without starting
17
+ * them. The children returned become the next level of the tree. Other
18
+ * components may not be set up yet, so don't reach for them. A Promise is
19
+ * awaited before the next component in the level starts.
49
20
  */
50
21
  performLocalInit(): Promise<LCMComponent[]> | LCMComponent[];
51
22
 
52
23
  /**
53
- * Phase 2: Inject dependencies from parent/siblings
54
- *
55
- * This phase should:
56
- * - Receive and store references to required dependencies
57
- * - Validate that required dependencies are provided
58
- * - Set up internal state based on dependencies
24
+ * Phase 2: take references to other components.
59
25
  *
60
- * This phase can be async and may:
61
- * - Load external data or resources
62
- * - Perform validation or setup operations
63
- * - Initialize internal components that depend on injected references
64
- *
65
- * @param deps Record of dependency name to dependency instance
66
- * @returns Promise<void> or void - can be async
26
+ * Every component in the tree has finished performLocalInit by now, so a
27
+ * parent can hand its children their siblings, or itself. The controller
28
+ * doesn't await a Promise returned here: activate can start before it
29
+ * resolves, so do async work in activate instead.
67
30
  */
68
31
  setupDependencies(): Promise<void> | void;
69
32
 
70
33
  /**
71
- * Phase 3: Activate component when all dependencies are ready
72
- *
73
- * This phase should:
74
- * - Complete final initialization
75
- * - Enable component functionality
76
- * - Start listening for external events
77
- * - Begin normal operation
34
+ * Phase 3: start working. Subscribe to events, load data, render.
78
35
  *
79
- * This phase can be async and may:
80
- * - Connect to external services
81
- * - Load initial data
82
- * - Emit ready notifications
83
- *
84
- * @returns Promise<void> or void - can be async
36
+ * Every component has finished setupDependencies. A level's activate
37
+ * calls run together, and the next level starts once all of them resolve.
85
38
  */
86
39
  activate(): Promise<void> | void;
87
40
 
88
41
  /**
89
- * Cleanup phase: Deactivate component and clean up resources
90
- *
91
- * This should:
92
- * - Stop all ongoing operations
93
- * - Remove event listeners
94
- * - Clean up external connections
95
- * - Dispose of child components
96
- *
97
- * @returns Promise<void> or void - can be async
42
+ * Stop working and release what activate took: subscriptions, listeners,
43
+ * connections. LifecycleController.deactivateAll calls it on the children
44
+ * before the parent, so a component doesn't deactivate its children itself.
98
45
  */
99
46
  deactivate(): Promise<void> | void;
100
47
  }
@@ -8,19 +8,22 @@ import { EventBus, LifecycleEventTypes, LifecycleEventType } from './EventBus';
8
8
  import { ComponentLifecycleEvent } from './events';
9
9
 
10
10
  /**
11
- * LifecycleController - Orchestrates breadth-first component initialization
11
+ * Starts a tree of LCMComponents, one phase at a time over the whole tree.
12
12
  *
13
- * This controller implements a breadth-first traversal of the component tree
14
- * followed by phase-wise initialization with synchronization barriers.
13
+ * initializeFromRoot runs three phases, and each one finishes for every
14
+ * component before the next one starts:
15
+ * 1. performLocalInit, breadth-first from the root. Each component returns its
16
+ * children, which become the next level. Within a level, one component's
17
+ * call finishes (its Promise included) before the next one's starts.
18
+ * 2. setupDependencies, in the same order. A Promise it returns isn't awaited.
19
+ * 3. activate, level by level. A level's calls run together, and the next
20
+ * level starts once all of them have resolved.
15
21
  *
16
- * Process:
17
- * 1. Discovery Phase: Traverse component tree to find all components
18
- * 2. DOM Binding Phase: All components bind to DOM simultaneously
19
- * 3. Dependency Injection Phase: All components receive dependencies
20
- * 4. Activation Phase: All components complete initialization
21
- *
22
- * Each phase acts as a synchronization barrier - no component can proceed
23
- * to the next phase until ALL components have completed the current phase.
22
+ * deactivateAll runs deactivate the other way, leaves first. A component
23
+ * returned by two parents is an error, and so is a second initializeFromRoot
24
+ * on the same controller. A phase that throws or rejects rejects
25
+ * initializeFromRoot, and the phases after it don't run.
26
+ * See https://panyam.github.io/goapplib/guide/components/.
24
27
  */
25
28
  export class LifecycleController {
26
29
  private allComponents: LCMComponent[];
@@ -47,8 +50,7 @@ export class LifecycleController {
47
50
  * Initialize component tree starting from root component
48
51
  *
49
52
  * @param rootComponent The root component to start initialization from
50
- * @param rootName Optional name for the root component (for debugging)
51
- * @returns Promise that resolves when all components are fully initialized
53
+ * @returns Promise that resolves when every component has activated
52
54
  */
53
55
  public async initializeFromRoot(rootComponent: LCMComponent): Promise<void> {
54
56
  // Phase 1 - Performance post-load setup where each parent will have the change
@@ -87,6 +89,7 @@ export class LifecycleController {
87
89
  `Component hierarchies must form a tree structure where each component has exactly one parent.`
88
90
  );
89
91
  }
92
+ visited.add(component);
90
93
 
91
94
  this.emitEvent(LifecycleEventTypes.LOCAL_INIT_STARTED, component, level)
92
95
  const result = component.performLocalInit()