effectable 0.1.0

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.
Files changed (124) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +157 -0
  3. package/build/LICENSE +21 -0
  4. package/build/bootstrap/bootstrap.d.ts +32 -0
  5. package/build/bootstrap/bootstrap.d.ts.map +1 -0
  6. package/build/bootstrap/bootstrap.js +179 -0
  7. package/build/bootstrap/bootstrap.js.map +1 -0
  8. package/build/bootstrap/index.d.ts +9 -0
  9. package/build/bootstrap/index.d.ts.map +1 -0
  10. package/build/bootstrap/index.js +14 -0
  11. package/build/bootstrap/index.js.map +1 -0
  12. package/build/bootstrap/types.d.ts +105 -0
  13. package/build/bootstrap/types.d.ts.map +1 -0
  14. package/build/bootstrap/types.js +26 -0
  15. package/build/bootstrap/types.js.map +1 -0
  16. package/build/component/Component.d.ts +126 -0
  17. package/build/component/Component.d.ts.map +1 -0
  18. package/build/component/Component.js +123 -0
  19. package/build/component/Component.js.map +1 -0
  20. package/build/component/GraphRuntime.d.ts +457 -0
  21. package/build/component/GraphRuntime.d.ts.map +1 -0
  22. package/build/component/GraphRuntime.js +1168 -0
  23. package/build/component/GraphRuntime.js.map +1 -0
  24. package/build/component/constants.d.ts +1 -0
  25. package/build/component/constants.d.ts.map +1 -0
  26. package/build/component/constants.js +2 -0
  27. package/build/component/constants.js.map +1 -0
  28. package/build/component/context.d.ts +199 -0
  29. package/build/component/context.d.ts.map +1 -0
  30. package/build/component/context.js +262 -0
  31. package/build/component/context.js.map +1 -0
  32. package/build/component/graphRuntime.constants.d.ts +13 -0
  33. package/build/component/graphRuntime.constants.d.ts.map +1 -0
  34. package/build/component/graphRuntime.constants.js +15 -0
  35. package/build/component/graphRuntime.constants.js.map +1 -0
  36. package/build/component/h.d.ts +48 -0
  37. package/build/component/h.d.ts.map +1 -0
  38. package/build/component/h.js +72 -0
  39. package/build/component/h.js.map +1 -0
  40. package/build/component/index.d.ts +19 -0
  41. package/build/component/index.d.ts.map +1 -0
  42. package/build/component/index.js +39 -0
  43. package/build/component/index.js.map +1 -0
  44. package/build/component/lifecycle.d.ts +179 -0
  45. package/build/component/lifecycle.d.ts.map +1 -0
  46. package/build/component/lifecycle.js +367 -0
  47. package/build/component/lifecycle.js.map +1 -0
  48. package/build/component/refs.d.ts +105 -0
  49. package/build/component/refs.d.ts.map +1 -0
  50. package/build/component/refs.js +128 -0
  51. package/build/component/refs.js.map +1 -0
  52. package/build/component/types.d.ts +169 -0
  53. package/build/component/types.d.ts.map +1 -0
  54. package/build/component/types.js +40 -0
  55. package/build/component/types.js.map +1 -0
  56. package/build/connect/connect.d.ts +31 -0
  57. package/build/connect/connect.d.ts.map +1 -0
  58. package/build/connect/connect.js +500 -0
  59. package/build/connect/connect.js.map +1 -0
  60. package/build/connect/index.d.ts +8 -0
  61. package/build/connect/index.d.ts.map +1 -0
  62. package/build/connect/index.js +11 -0
  63. package/build/connect/index.js.map +1 -0
  64. package/build/connect/types.d.ts +90 -0
  65. package/build/connect/types.d.ts.map +1 -0
  66. package/build/connect/types.js +8 -0
  67. package/build/connect/types.js.map +1 -0
  68. package/build/index.d.ts +26 -0
  69. package/build/index.d.ts.map +1 -0
  70. package/build/index.js +60 -0
  71. package/build/index.js.map +1 -0
  72. package/build/runtime/BusDecorators.d.ts +113 -0
  73. package/build/runtime/BusDecorators.d.ts.map +1 -0
  74. package/build/runtime/BusDecorators.js +302 -0
  75. package/build/runtime/BusDecorators.js.map +1 -0
  76. package/build/runtime/CommandBus.d.ts +43 -0
  77. package/build/runtime/CommandBus.d.ts.map +1 -0
  78. package/build/runtime/CommandBus.js +65 -0
  79. package/build/runtime/CommandBus.js.map +1 -0
  80. package/build/runtime/EventBus.d.ts +50 -0
  81. package/build/runtime/EventBus.d.ts.map +1 -0
  82. package/build/runtime/EventBus.js +90 -0
  83. package/build/runtime/EventBus.js.map +1 -0
  84. package/build/runtime/HandleRegistry.d.ts +143 -0
  85. package/build/runtime/HandleRegistry.d.ts.map +1 -0
  86. package/build/runtime/HandleRegistry.js +244 -0
  87. package/build/runtime/HandleRegistry.js.map +1 -0
  88. package/build/runtime/QueryBus.d.ts +43 -0
  89. package/build/runtime/QueryBus.d.ts.map +1 -0
  90. package/build/runtime/QueryBus.js +65 -0
  91. package/build/runtime/QueryBus.js.map +1 -0
  92. package/build/runtime/index.d.ts +13 -0
  93. package/build/runtime/index.d.ts.map +1 -0
  94. package/build/runtime/index.js +32 -0
  95. package/build/runtime/index.js.map +1 -0
  96. package/build/runtime/types.d.ts +79 -0
  97. package/build/runtime/types.d.ts.map +1 -0
  98. package/build/runtime/types.js +8 -0
  99. package/build/runtime/types.js.map +1 -0
  100. package/build/store/createStore.d.ts +36 -0
  101. package/build/store/createStore.d.ts.map +1 -0
  102. package/build/store/createStore.js +131 -0
  103. package/build/store/createStore.js.map +1 -0
  104. package/build/store/index.d.ts +14 -0
  105. package/build/store/index.d.ts.map +1 -0
  106. package/build/store/index.js +39 -0
  107. package/build/store/index.js.map +1 -0
  108. package/build/store/middleware.d.ts +38 -0
  109. package/build/store/middleware.d.ts.map +1 -0
  110. package/build/store/middleware.js +99 -0
  111. package/build/store/middleware.js.map +1 -0
  112. package/build/store/selector.d.ts +62 -0
  113. package/build/store/selector.d.ts.map +1 -0
  114. package/build/store/selector.js +226 -0
  115. package/build/store/selector.js.map +1 -0
  116. package/build/store/semanticStateTree.d.ts +91 -0
  117. package/build/store/semanticStateTree.d.ts.map +1 -0
  118. package/build/store/semanticStateTree.js +263 -0
  119. package/build/store/semanticStateTree.js.map +1 -0
  120. package/build/store/types.d.ts +259 -0
  121. package/build/store/types.d.ts.map +1 -0
  122. package/build/store/types.js +28 -0
  123. package/build/store/types.js.map +1 -0
  124. package/package.json +109 -0
@@ -0,0 +1,72 @@
1
+ "use strict";
2
+ /**
3
+ * VirtualServiceNode factory for declarative component tree composition.
4
+ * Declarative element factory for a backend runtime graph (virtual service nodes).
5
+ *
6
+ * h() describes topology with no side effects — no network calls,
7
+ * subscriptions, or handler registration inside an h() call.
8
+ *
9
+ * @module Effectable/component/h
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.h = h;
13
+ /**
14
+ * Singleton: immutable empty children array used by default.
15
+ *
16
+ * Used in {@link h} when no children are passed, to avoid allocating `[]` on every call.
17
+ * `Object.freeze` preserves the immutability invariant of the {@link VirtualServiceNode} structure.
18
+ */
19
+ const EMPTY_CHILDREN = Object.freeze([]);
20
+ function h(type, props, refOrChildrenOrKey, childrenOrKey, maybeKey) {
21
+ const resolvedProps = (props === undefined ? {} : props);
22
+ // Fast-path: most common case — h(type) / h(type, props) without ref/children/key.
23
+ // Return a shape-stable object without intermediate checks (41x speedup).
24
+ if (refOrChildrenOrKey === undefined) {
25
+ return {
26
+ type: type,
27
+ props: resolvedProps,
28
+ ref: undefined,
29
+ children: EMPTY_CHILDREN,
30
+ };
31
+ }
32
+ let resolvedRef;
33
+ let resolvedChildren;
34
+ let resolvedKey;
35
+ if (typeof refOrChildrenOrKey === 'string') {
36
+ resolvedRef = undefined;
37
+ resolvedChildren = EMPTY_CHILDREN;
38
+ resolvedKey = refOrChildrenOrKey;
39
+ }
40
+ else if (Array.isArray(refOrChildrenOrKey)) {
41
+ resolvedRef = undefined;
42
+ resolvedChildren = refOrChildrenOrKey;
43
+ resolvedKey = typeof childrenOrKey === 'string' ? childrenOrKey : undefined;
44
+ }
45
+ else {
46
+ resolvedRef = refOrChildrenOrKey;
47
+ if (typeof childrenOrKey === 'string') {
48
+ resolvedChildren = EMPTY_CHILDREN;
49
+ resolvedKey = childrenOrKey;
50
+ }
51
+ else {
52
+ resolvedChildren = childrenOrKey ?? EMPTY_CHILDREN;
53
+ resolvedKey = maybeKey;
54
+ }
55
+ }
56
+ if (resolvedKey === undefined) {
57
+ return {
58
+ type: type,
59
+ props: resolvedProps,
60
+ ref: resolvedRef,
61
+ children: resolvedChildren,
62
+ };
63
+ }
64
+ return {
65
+ type: type,
66
+ props: resolvedProps,
67
+ ref: resolvedRef,
68
+ children: resolvedChildren,
69
+ key: resolvedKey,
70
+ };
71
+ }
72
+ //# sourceMappingURL=h.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"h.js","sourceRoot":"","sources":["../../src/component/h.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAyDH,cA2DC;AAhHD;;;;;GAKG;AACH,MAAM,cAAc,GAAkC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAkC,CAAC;AA+CzG,SAAgB,CAAC,CACf,IAA6B,EAC7B,KAAS,EACT,kBAAuE,EACvE,aAA6C,EAC7C,QAAiB;IAEjB,MAAM,aAAa,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAM,CAAC;IAE9D,mFAAmF;IACnF,0EAA0E;IAC1E,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO;YACL,IAAI,EAAE,IAAqC;YAC3C,KAAK,EAAE,aAAa;YACpB,GAAG,EAAE,SAAS;YACd,QAAQ,EAAE,cAAsC;SACjD,CAAC;IACJ,CAAC;IAED,IAAI,WAA2C,CAAC;IAChD,IAAI,gBAAsC,CAAC;IAC3C,IAAI,WAA+B,CAAC;IAEpC,IAAI,OAAO,kBAAkB,KAAK,QAAQ,EAAE,CAAC;QAC3C,WAAW,GAAG,SAAS,CAAC;QACxB,gBAAgB,GAAG,cAAsC,CAAC;QAC1D,WAAW,GAAG,kBAAkB,CAAC;IACnC,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC7C,WAAW,GAAG,SAAS,CAAC;QACxB,gBAAgB,GAAG,kBAAkB,CAAC;QACtC,WAAW,GAAG,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,CAAC;SAAM,CAAC;QACN,WAAW,GAAG,kBAAkB,CAAC;QACjC,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;YACtC,gBAAgB,GAAG,cAAsC,CAAC;YAC1D,WAAW,GAAG,aAAa,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,gBAAgB,GAAG,aAAa,IAAK,cAAuC,CAAC;YAC7E,WAAW,GAAG,QAAQ,CAAC;QACzB,CAAC;IACH,CAAC;IAED,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,IAAqC;YAC3C,KAAK,EAAE,aAAa;YACpB,GAAG,EAAE,WAAW;YAChB,QAAQ,EAAE,gBAAgB;SAC3B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,IAAqC;QAC3C,KAAK,EAAE,aAAa;QACpB,GAAG,EAAE,WAAW;QAChB,QAAQ,EAAE,gBAAgB;QAC1B,GAAG,EAAE,WAAW;KACjB,CAAC;AACJ,CAAC"}
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Re-exports types, the base Component class, and declarative composition utilities for Effectable/component.
3
+ *
4
+ * @module Effectable/component
5
+ */
6
+ export type { Lifecycle, Disposable, RuntimePropsReceiver, RefObject, VirtualServiceNode, NodeLifecycleStatus, FiberEffectTag, FiberInspectNode, Fiber, ComponentConstructor, } from './types';
7
+ export { RUNTIME_PROPS_RECEIVER, FIBER_EFFECT_TAG } from './types';
8
+ export { Component } from './Component';
9
+ export type { SetStateUpdate } from './Component';
10
+ export { h } from './h';
11
+ export { LifecycleEngine } from './lifecycle';
12
+ export type { LifecycleTransitionResult } from './lifecycle';
13
+ export { UseRef, UseImperativeHandle, getRefFields, getImperativeHandleMethods } from './refs';
14
+ export type { RefFieldMeta, ImperativeHandleMeta } from './refs';
15
+ export { REF_FIELDS_META_KEY, IMPERATIVE_HANDLE_META_KEY } from './refs';
16
+ export { createContext, extendScope, readFromScope, ContextProvider, UseContext, getContextFields, injectContextFields, EMPTY_CONTEXT_SCOPE, CONTEXT_FIELDS_META_KEY, } from './context';
17
+ export type { ContextToken, ContextScope, ContextProviderProps, ContextFieldMeta, } from './context';
18
+ export { GraphRuntime, makeFiberEffectTag } from './GraphRuntime';
19
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,SAAS,EACT,UAAU,EACV,oBAAoB,EACpB,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,KAAK,EACL,oBAAoB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,QAAQ,CAAC;AAC/F,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,EACb,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
@@ -0,0 +1,39 @@
1
+ "use strict";
2
+ /**
3
+ * Re-exports types, the base Component class, and declarative composition utilities for Effectable/component.
4
+ *
5
+ * @module Effectable/component
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.makeFiberEffectTag = exports.GraphRuntime = exports.CONTEXT_FIELDS_META_KEY = exports.EMPTY_CONTEXT_SCOPE = exports.injectContextFields = exports.getContextFields = exports.UseContext = exports.ContextProvider = exports.readFromScope = exports.extendScope = exports.createContext = exports.IMPERATIVE_HANDLE_META_KEY = exports.REF_FIELDS_META_KEY = exports.getImperativeHandleMethods = exports.getRefFields = exports.UseImperativeHandle = exports.UseRef = exports.LifecycleEngine = exports.h = exports.Component = exports.FIBER_EFFECT_TAG = exports.RUNTIME_PROPS_RECEIVER = void 0;
9
+ var types_1 = require("./types");
10
+ Object.defineProperty(exports, "RUNTIME_PROPS_RECEIVER", { enumerable: true, get: function () { return types_1.RUNTIME_PROPS_RECEIVER; } });
11
+ Object.defineProperty(exports, "FIBER_EFFECT_TAG", { enumerable: true, get: function () { return types_1.FIBER_EFFECT_TAG; } });
12
+ var Component_1 = require("./Component");
13
+ Object.defineProperty(exports, "Component", { enumerable: true, get: function () { return Component_1.Component; } });
14
+ var h_1 = require("./h");
15
+ Object.defineProperty(exports, "h", { enumerable: true, get: function () { return h_1.h; } });
16
+ var lifecycle_1 = require("./lifecycle");
17
+ Object.defineProperty(exports, "LifecycleEngine", { enumerable: true, get: function () { return lifecycle_1.LifecycleEngine; } });
18
+ var refs_1 = require("./refs");
19
+ Object.defineProperty(exports, "UseRef", { enumerable: true, get: function () { return refs_1.UseRef; } });
20
+ Object.defineProperty(exports, "UseImperativeHandle", { enumerable: true, get: function () { return refs_1.UseImperativeHandle; } });
21
+ Object.defineProperty(exports, "getRefFields", { enumerable: true, get: function () { return refs_1.getRefFields; } });
22
+ Object.defineProperty(exports, "getImperativeHandleMethods", { enumerable: true, get: function () { return refs_1.getImperativeHandleMethods; } });
23
+ var refs_2 = require("./refs");
24
+ Object.defineProperty(exports, "REF_FIELDS_META_KEY", { enumerable: true, get: function () { return refs_2.REF_FIELDS_META_KEY; } });
25
+ Object.defineProperty(exports, "IMPERATIVE_HANDLE_META_KEY", { enumerable: true, get: function () { return refs_2.IMPERATIVE_HANDLE_META_KEY; } });
26
+ var context_1 = require("./context");
27
+ Object.defineProperty(exports, "createContext", { enumerable: true, get: function () { return context_1.createContext; } });
28
+ Object.defineProperty(exports, "extendScope", { enumerable: true, get: function () { return context_1.extendScope; } });
29
+ Object.defineProperty(exports, "readFromScope", { enumerable: true, get: function () { return context_1.readFromScope; } });
30
+ Object.defineProperty(exports, "ContextProvider", { enumerable: true, get: function () { return context_1.ContextProvider; } });
31
+ Object.defineProperty(exports, "UseContext", { enumerable: true, get: function () { return context_1.UseContext; } });
32
+ Object.defineProperty(exports, "getContextFields", { enumerable: true, get: function () { return context_1.getContextFields; } });
33
+ Object.defineProperty(exports, "injectContextFields", { enumerable: true, get: function () { return context_1.injectContextFields; } });
34
+ Object.defineProperty(exports, "EMPTY_CONTEXT_SCOPE", { enumerable: true, get: function () { return context_1.EMPTY_CONTEXT_SCOPE; } });
35
+ Object.defineProperty(exports, "CONTEXT_FIELDS_META_KEY", { enumerable: true, get: function () { return context_1.CONTEXT_FIELDS_META_KEY; } });
36
+ var GraphRuntime_1 = require("./GraphRuntime");
37
+ Object.defineProperty(exports, "GraphRuntime", { enumerable: true, get: function () { return GraphRuntime_1.GraphRuntime; } });
38
+ Object.defineProperty(exports, "makeFiberEffectTag", { enumerable: true, get: function () { return GraphRuntime_1.makeFiberEffectTag; } });
39
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAcH,iCAAmE;AAA1D,+GAAA,sBAAsB,OAAA;AAAE,yGAAA,gBAAgB,OAAA;AACjD,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAElB,yBAAwB;AAAf,sFAAA,CAAC,OAAA;AACV,yCAA8C;AAArC,4GAAA,eAAe,OAAA;AAExB,+BAA+F;AAAtF,8FAAA,MAAM,OAAA;AAAE,2GAAA,mBAAmB,OAAA;AAAE,oGAAA,YAAY,OAAA;AAAE,kHAAA,0BAA0B,OAAA;AAE9E,+BAAyE;AAAhE,2GAAA,mBAAmB,OAAA;AAAE,kHAAA,0BAA0B,OAAA;AACxD,qCAUmB;AATjB,wGAAA,aAAa,OAAA;AACb,sGAAA,WAAW,OAAA;AACX,wGAAA,aAAa,OAAA;AACb,0GAAA,eAAe,OAAA;AACf,qGAAA,UAAU,OAAA;AACV,2GAAA,gBAAgB,OAAA;AAChB,8GAAA,mBAAmB,OAAA;AACnB,8GAAA,mBAAmB,OAAA;AACnB,kHAAA,uBAAuB,OAAA;AAQzB,+CAAkE;AAAzD,4GAAA,YAAY,OAAA;AAAE,kHAAA,kBAAkB,OAAA"}
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Node lifecycle engine (`LifecycleEngine`) and transition result type.
3
+ *
4
+ * The state machine defines stage order: `registered` → `resolved` → `created` →
5
+ * `mounted` → `ready` → `unmounting` → `unmounted` → `destroyed`.
6
+ * Any stage may transition to `failed`; there is no reverse transition from `failed`
7
+ * (except forced `destroy` via teardown scenarios).
8
+ *
9
+ * Public component hooks are called in the expected order:
10
+ * - startup: `onMount`
11
+ * - in stage `ready`: `onUpdate` (as decided by GraphRuntime)
12
+ * - shutdown / cleanup: `onUnmount`
13
+ *
14
+ * @module Effectable/component/lifecycle
15
+ */
16
+ import type { Component } from './Component';
17
+ import type { NodeLifecycleStatus } from './types';
18
+ /**
19
+ * Result of an asynchronous lifecycle transition attempt (startup / shutdown).
20
+ *
21
+ * Errors from hooks are not rethrown: on failure the branch
22
+ * `{ ok: false, error }` is returned; success is `{ ok: true }`.
23
+ */
24
+ export type LifecycleTransitionResult = {
25
+ ok: true;
26
+ } | {
27
+ ok: false;
28
+ error: unknown;
29
+ };
30
+ /**
31
+ * Target stage name for {@link LifecycleEngine.canTransitionTo}: only “forward” along the graph,
32
+ * without returning to already passed stages (except special rules for `failed`).
33
+ */
34
+ type ForwardStage = 'resolved' | 'created' | 'mounted' | 'ready' | 'unmounting' | 'unmounted' | 'destroyed' | 'failed';
35
+ /**
36
+ * Lifecycle state machine for one node in GraphRuntime: one instance
37
+ * per node (fiber).
38
+ *
39
+ * Invariants:
40
+ * - stages mostly advance monotonically; update passes are allowed in `ready`;
41
+ * - after `failed`, further transitions are limited (see {@link canTransitionTo});
42
+ * - {@link Component.onUnmount} is called at most once per instance.
43
+ *
44
+ * @example
45
+ * const engine = new LifecycleEngine();
46
+ * engine.initHookFlags(component);
47
+ * await engine.runStartup(component);
48
+ */
49
+ export declare class LifecycleEngine {
50
+ /**
51
+ * Current stage as a number (see {@link STAGE}): comparisons without string lookups.
52
+ */
53
+ private currentStage;
54
+ private unmountCalled;
55
+ /**
56
+ * Bit flags for which hooks the component has.
57
+ * 0 — hooks not initialized or absent (fast-exit in runStartup/runShutdown).
58
+ * Set via initHookFlags() after instance creation.
59
+ */
60
+ private hookFlags;
61
+ /**
62
+ * Whether hookFlags were initialized via initHookFlags().
63
+ * Without this, the fast-exit on hookFlags === 0 would apply before initialization.
64
+ */
65
+ private hookFlagsInitialized;
66
+ /**
67
+ * Returns the string node status for the external API (GraphRuntime, debugging, UI).
68
+ *
69
+ * @returns {NodeLifecycleStatus} current stage as `NodeLifecycleStatus`
70
+ */
71
+ getStatus(): NodeLifecycleStatus;
72
+ /**
73
+ * Computes and stores a bit mask of hook methods present on the instance.
74
+ * Must be called exactly once after instance creation (e.g. from materialize).
75
+ * Lets {@link runStartup} and {@link runShutdown} skip per-hook checks
76
+ * when none are declared.
77
+ *
78
+ * @param {Component<unknown, unknown>} instance - component instance with optional hooks
79
+ * @returns {void}
80
+ */
81
+ initHookFlags(instance: Component<unknown, unknown>): void;
82
+ /**
83
+ * Startup phase: if present — call `onMount`, advance stages to `ready`.
84
+ * On exception: stage already `Mounted` → {@link runFailedCleanup}(`wasMounted=true`)
85
+ * (attempt `onUnmount` + teardown), result `{ ok: false, error }`.
86
+ *
87
+ * Returns a synchronous {@link LifecycleTransitionResult} if `onMount` returned
88
+ * a non-thenable value (sync fast-path); otherwise a Promise.
89
+ * `await` works correctly with either union branch.
90
+ *
91
+ * @param {Component<unknown, unknown>} instance - component instance
92
+ * @returns {LifecycleTransitionResult | Promise<LifecycleTransitionResult>}
93
+ */
94
+ runStartup(instance: Component<unknown, unknown>): LifecycleTransitionResult | Promise<LifecycleTransitionResult>;
95
+ /**
96
+ * Async continuation of {@link runStartup} after `onMount` returned a Promise.
97
+ *
98
+ * @param {Component<unknown, unknown>} instance - component instance
99
+ * @param {PromiseLike<unknown>} pending - Promise from onMount
100
+ * @returns {Promise<LifecycleTransitionResult>}
101
+ */
102
+ private continueStartupAsync;
103
+ /**
104
+ * Shutdown phase: if needed `onUnmount`, stages `unmounting` → `unmounted` → `destroyed`.
105
+ * If the node is already `destroyed`, noop. An error in `onUnmount` is returned as `{ ok: false, error }`.
106
+ *
107
+ * Returns a synchronous {@link LifecycleTransitionResult} if `onUnmount` returned non-thenable
108
+ * (sync fast-path); otherwise a Promise. `await` works correctly
109
+ * with either union branch.
110
+ *
111
+ * @param {Component<unknown, unknown>} instance - component instance
112
+ * @returns {LifecycleTransitionResult | Promise<LifecycleTransitionResult>}
113
+ */
114
+ runShutdown(instance: Component<unknown, unknown>): LifecycleTransitionResult | Promise<LifecycleTransitionResult>;
115
+ /**
116
+ * Async continuation of {@link runShutdown} after `onUnmount` returned a Promise.
117
+ *
118
+ * @param {PromiseLike<unknown>} pendingUnmount - Promise from onUnmount
119
+ * @returns {Promise<LifecycleTransitionResult>}
120
+ */
121
+ private continueShutdownAsync;
122
+ /**
123
+ * Forced cleanup after failure: stage `failed`, if `wasMounted` — attempt
124
+ * `onUnmount` (errors swallowed), then final teardown.
125
+ * Used on `onMount` fail (stage already `Mounted`) and by GraphRuntime on errors
126
+ * outside startup (e.g. during update).
127
+ *
128
+ * Returns `void` synchronously if `onUnmount` is absent or returned non-thenable;
129
+ * otherwise a Promise.
130
+ *
131
+ * @param {Component<unknown, unknown>} instance - component instance
132
+ * @param {boolean} wasMounted - `true` if the node had already mounted before the error
133
+ * @returns {void | Promise<void>}
134
+ */
135
+ runFailedCleanup(instance: Component<unknown, unknown>, wasMounted: boolean): void | Promise<void>;
136
+ /**
137
+ * Async continuation of {@link runFailedCleanup} after async unmount.
138
+ *
139
+ * @param {PromiseLike<unknown>} pendingUnmount - Promise from onUnmount
140
+ * @returns {Promise<void>}
141
+ */
142
+ private continueFailedCleanupAsync;
143
+ /**
144
+ * Idempotent teardown: marks the node as `destroyed`. No `onDestroy` call
145
+ * (legacy hook removed); side-effect cleanup happens in `onUnmount`.
146
+ *
147
+ * @returns {void | Promise<void>} always `void` (signature kept for compatibility)
148
+ */
149
+ private runForcedDestroy;
150
+ /**
151
+ * Whether the node can accept an update pass (`onUpdate`): only stage `ready`.
152
+ *
153
+ * @returns {boolean} `true` if an update-pass may be called
154
+ */
155
+ canUpdate(): boolean;
156
+ /**
157
+ * Whether the node is in a terminal stage: `destroyed` or `failed` (further work with the node is not expected).
158
+ *
159
+ * @returns {boolean} `true` for `destroyed` and `failed`
160
+ */
161
+ isTerminated(): boolean;
162
+ /**
163
+ * Moves the node to `failed` without calling hooks (external error, marking in GraphRuntime).
164
+ * If the node is already terminal, state is unchanged.
165
+ *
166
+ * @returns {void}
167
+ */
168
+ markFailed(): void;
169
+ /**
170
+ * Whether a “forward” transition to `target` is allowed relative to the current numeric stage.
171
+ * From `failed` only a transition to `destroyed` is allowed (aligned with forced teardown).
172
+ *
173
+ * @param {ForwardStage} target - target stage under test by string name
174
+ * @returns {boolean} `true` if the target stage is strictly “later” than current (or special case `failed`→`destroyed`)
175
+ */
176
+ canTransitionTo(target: ForwardStage): boolean;
177
+ }
178
+ export {};
179
+ //# sourceMappingURL=lifecycle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/component/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAElC;;;GAGG;AACH,KAAK,YAAY,GACb,UAAU,GACV,SAAS,GACT,SAAS,GACT,OAAO,GACP,YAAY,GACZ,WAAW,GACX,WAAW,GACX,QAAQ,CAAC;AAoFb;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAAS;IAErC;;;;OAIG;IACI,SAAS,IAAK,mBAAmB;IAIxC;;;;;;;;OAQG;IACI,aAAa,CAAE,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI;IASlE;;;;;;;;;;;OAWG;IACI,UAAU,CACf,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,GACpC,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAiCjE;;;;;;OAMG;YACW,oBAAoB;IAiBlC;;;;;;;;;;OAUG;IACI,WAAW,CAChB,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,GACpC,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAmCjE;;;;;OAKG;YACW,qBAAqB;IAmBnC;;;;;;;;;;;;OAYG;IACI,gBAAgB,CACrB,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,UAAU,EAAE,OAAO,GAClB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvB;;;;;OAKG;YACW,0BAA0B;IAexC;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;;OAIG;IACI,SAAS,IAAK,OAAO;IAI5B;;;;OAIG;IACI,YAAY,IAAK,OAAO;IAM/B;;;;;OAKG;IACI,UAAU,IAAK,IAAI;IAM1B;;;;;;OAMG;IACI,eAAe,CAAE,MAAM,EAAE,YAAY,GAAG,OAAO;CAQvD"}