@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/README.md +5 -3
- package/dist/index.d.mts +39 -89
- package/dist/index.d.ts +39 -89
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
- package/src/LCMComponent.ts +24 -77
- package/src/LifecycleController.ts +16 -13
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@panyam/tsappkit",
|
|
3
|
-
"version": "0.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",
|
package/src/LCMComponent.ts
CHANGED
|
@@ -1,100 +1,47 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
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
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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:
|
|
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
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
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:
|
|
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
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
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:
|
|
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
|
-
*
|
|
80
|
-
*
|
|
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
|
-
*
|
|
90
|
-
*
|
|
91
|
-
*
|
|
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
|
-
*
|
|
11
|
+
* Starts a tree of LCMComponents, one phase at a time over the whole tree.
|
|
12
12
|
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
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
|
-
* @
|
|
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()
|