@cldmv/slothlet 2.10.0 → 3.0.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 (188) hide show
  1. package/AGENT-USAGE.md +365 -294
  2. package/README.md +556 -233
  3. package/dist/lib/builders/api-assignment.mjs +605 -0
  4. package/dist/lib/builders/api_builder.mjs +1073 -0
  5. package/dist/lib/builders/builder.mjs +94 -0
  6. package/dist/lib/builders/modes-processor.mjs +1816 -0
  7. package/dist/lib/errors.mjs +227 -0
  8. package/dist/lib/factories/component-base.mjs +96 -0
  9. package/dist/lib/factories/context.mjs +38 -0
  10. package/dist/lib/handlers/api-cache-manager.mjs +216 -0
  11. package/dist/lib/handlers/api-manager.mjs +2364 -0
  12. package/dist/lib/handlers/context-async.mjs +184 -0
  13. package/dist/lib/handlers/context-live.mjs +184 -0
  14. package/dist/lib/handlers/hook-manager.mjs +789 -0
  15. package/dist/lib/handlers/lifecycle-token.mjs +44 -0
  16. package/dist/lib/handlers/lifecycle.mjs +131 -0
  17. package/dist/lib/handlers/materialize-manager.mjs +64 -0
  18. package/dist/lib/handlers/metadata.mjs +500 -0
  19. package/dist/lib/handlers/ownership.mjs +338 -0
  20. package/dist/lib/handlers/unified-wrapper.mjs +3031 -0
  21. package/dist/lib/helpers/class-instance-wrapper.mjs +125 -0
  22. package/dist/lib/helpers/config.mjs +343 -0
  23. package/dist/lib/helpers/eventemitter-context.mjs +365 -0
  24. package/dist/lib/helpers/hint-detector.mjs +63 -0
  25. package/dist/lib/helpers/modes-utils.mjs +53 -0
  26. package/dist/lib/helpers/resolve-from-caller.mjs +125 -85
  27. package/dist/lib/helpers/sanitize.mjs +247 -168
  28. package/dist/lib/helpers/utilities.mjs +46 -81
  29. package/dist/lib/i18n/languages/de-de.json +377 -0
  30. package/dist/lib/i18n/languages/en-gb.json +377 -0
  31. package/dist/lib/i18n/languages/en-us.json +377 -0
  32. package/dist/lib/i18n/languages/es-mx.json +377 -0
  33. package/dist/lib/i18n/languages/fr-fr.json +377 -0
  34. package/dist/lib/i18n/languages/hi-in.json +377 -0
  35. package/dist/lib/i18n/languages/ja-jp.json +377 -0
  36. package/dist/lib/i18n/languages/ko-kr.json +377 -0
  37. package/dist/lib/i18n/languages/pt-br.json +377 -0
  38. package/dist/lib/i18n/languages/ru-ru.json +377 -0
  39. package/dist/lib/i18n/languages/zh-cn.json +377 -0
  40. package/dist/lib/i18n/translations.mjs +140 -0
  41. package/dist/lib/modes/eager.mjs +75 -0
  42. package/dist/lib/modes/lazy.mjs +97 -0
  43. package/dist/lib/processors/flatten.mjs +453 -0
  44. package/dist/lib/processors/loader.mjs +355 -0
  45. package/dist/lib/processors/type-generator.mjs +291 -0
  46. package/dist/lib/processors/typescript.mjs +188 -0
  47. package/dist/lib/runtime/runtime-asynclocalstorage.mjs +80 -522
  48. package/dist/lib/runtime/runtime-livebindings.mjs +45 -390
  49. package/dist/lib/runtime/runtime.mjs +39 -159
  50. package/dist/slothlet.mjs +529 -700
  51. package/docs/API-RULES.md +497 -617
  52. package/index.cjs +4 -4
  53. package/index.mjs +82 -45
  54. package/package.json +139 -26
  55. package/types/dist/lib/builders/api-assignment.d.mts +97 -0
  56. package/types/dist/lib/builders/api-assignment.d.mts.map +1 -0
  57. package/types/dist/lib/builders/api_builder.d.mts +96 -0
  58. package/types/dist/lib/builders/api_builder.d.mts.map +1 -0
  59. package/types/dist/lib/builders/builder.d.mts +60 -0
  60. package/types/dist/lib/builders/builder.d.mts.map +1 -0
  61. package/types/dist/lib/builders/modes-processor.d.mts +32 -0
  62. package/types/dist/lib/builders/modes-processor.d.mts.map +1 -0
  63. package/types/dist/lib/errors.d.mts +118 -0
  64. package/types/dist/lib/errors.d.mts.map +1 -0
  65. package/types/dist/lib/factories/component-base.d.mts +182 -0
  66. package/types/dist/lib/factories/component-base.d.mts.map +1 -0
  67. package/types/dist/lib/factories/context.d.mts +26 -0
  68. package/types/dist/lib/factories/context.d.mts.map +1 -0
  69. package/types/dist/lib/handlers/api-cache-manager.d.mts +208 -0
  70. package/types/dist/lib/handlers/api-cache-manager.d.mts.map +1 -0
  71. package/types/dist/lib/handlers/api-manager.d.mts +392 -0
  72. package/types/dist/lib/handlers/api-manager.d.mts.map +1 -0
  73. package/types/dist/lib/handlers/context-async.d.mts +66 -0
  74. package/types/dist/lib/handlers/context-async.d.mts.map +1 -0
  75. package/types/dist/lib/handlers/context-live.d.mts +65 -0
  76. package/types/dist/lib/handlers/context-live.d.mts.map +1 -0
  77. package/types/dist/lib/handlers/hook-manager.d.mts +199 -0
  78. package/types/dist/lib/handlers/hook-manager.d.mts.map +1 -0
  79. package/types/dist/lib/handlers/lifecycle-token.d.mts +49 -0
  80. package/types/dist/lib/handlers/lifecycle-token.d.mts.map +1 -0
  81. package/types/dist/lib/handlers/lifecycle.d.mts +90 -0
  82. package/types/dist/lib/handlers/lifecycle.d.mts.map +1 -0
  83. package/types/dist/lib/handlers/materialize-manager.d.mts +75 -0
  84. package/types/dist/lib/handlers/materialize-manager.d.mts.map +1 -0
  85. package/types/dist/lib/handlers/metadata.d.mts +215 -0
  86. package/types/dist/lib/handlers/metadata.d.mts.map +1 -0
  87. package/types/dist/lib/handlers/ownership.d.mts +170 -0
  88. package/types/dist/lib/handlers/ownership.d.mts.map +1 -0
  89. package/types/dist/lib/handlers/unified-wrapper.d.mts +250 -0
  90. package/types/dist/lib/handlers/unified-wrapper.d.mts.map +1 -0
  91. package/types/dist/lib/helpers/class-instance-wrapper.d.mts +54 -0
  92. package/types/dist/lib/helpers/class-instance-wrapper.d.mts.map +1 -0
  93. package/types/dist/lib/helpers/config.d.mts +96 -0
  94. package/types/dist/lib/helpers/config.d.mts.map +1 -0
  95. package/types/dist/lib/helpers/eventemitter-context.d.mts +31 -0
  96. package/types/dist/lib/helpers/eventemitter-context.d.mts.map +1 -0
  97. package/types/dist/lib/helpers/hint-detector.d.mts +20 -0
  98. package/types/dist/lib/helpers/hint-detector.d.mts.map +1 -0
  99. package/types/dist/lib/helpers/modes-utils.d.mts +35 -0
  100. package/types/dist/lib/helpers/modes-utils.d.mts.map +1 -0
  101. package/types/dist/lib/helpers/resolve-from-caller.d.mts +29 -145
  102. package/types/dist/lib/helpers/resolve-from-caller.d.mts.map +1 -1
  103. package/types/dist/lib/helpers/sanitize.d.mts +95 -94
  104. package/types/dist/lib/helpers/sanitize.d.mts.map +1 -1
  105. package/types/dist/lib/helpers/utilities.d.mts +53 -116
  106. package/types/dist/lib/helpers/utilities.d.mts.map +1 -1
  107. package/types/dist/lib/i18n/translations.d.mts +39 -0
  108. package/types/dist/lib/i18n/translations.d.mts.map +1 -0
  109. package/types/dist/lib/modes/eager.d.mts +36 -0
  110. package/types/dist/lib/modes/eager.d.mts.map +1 -0
  111. package/types/dist/lib/modes/lazy.d.mts +49 -0
  112. package/types/dist/lib/modes/lazy.d.mts.map +1 -0
  113. package/types/dist/lib/processors/flatten.d.mts +114 -0
  114. package/types/dist/lib/processors/flatten.d.mts.map +1 -0
  115. package/types/dist/lib/processors/loader.d.mts +47 -0
  116. package/types/dist/lib/processors/loader.d.mts.map +1 -0
  117. package/types/dist/lib/processors/type-generator.d.mts +19 -0
  118. package/types/dist/lib/processors/type-generator.d.mts.map +1 -0
  119. package/types/dist/lib/processors/typescript.d.mts +55 -0
  120. package/types/dist/lib/processors/typescript.d.mts.map +1 -0
  121. package/types/dist/lib/runtime/runtime-asynclocalstorage.d.mts +47 -42
  122. package/types/dist/lib/runtime/runtime-asynclocalstorage.d.mts.map +1 -1
  123. package/types/dist/lib/runtime/runtime-livebindings.d.mts +34 -65
  124. package/types/dist/lib/runtime/runtime-livebindings.d.mts.map +1 -1
  125. package/types/dist/lib/runtime/runtime.d.mts +39 -9
  126. package/types/dist/lib/runtime/runtime.d.mts.map +1 -1
  127. package/types/dist/slothlet.d.mts +186 -105
  128. package/types/dist/slothlet.d.mts.map +1 -1
  129. package/types/index.d.mts +1 -3
  130. package/dist/lib/engine/README.md +0 -21
  131. package/dist/lib/engine/slothlet_child.mjs +0 -59
  132. package/dist/lib/engine/slothlet_engine.mjs +0 -372
  133. package/dist/lib/engine/slothlet_esm.mjs +0 -230
  134. package/dist/lib/engine/slothlet_helpers.mjs +0 -455
  135. package/dist/lib/engine/slothlet_worker.mjs +0 -149
  136. package/dist/lib/helpers/als-eventemitter.mjs +0 -256
  137. package/dist/lib/helpers/api_builder/add_api.mjs +0 -292
  138. package/dist/lib/helpers/api_builder/analysis.mjs +0 -532
  139. package/dist/lib/helpers/api_builder/construction.mjs +0 -457
  140. package/dist/lib/helpers/api_builder/decisions.mjs +0 -737
  141. package/dist/lib/helpers/api_builder/metadata.mjs +0 -248
  142. package/dist/lib/helpers/api_builder.mjs +0 -41
  143. package/dist/lib/helpers/auto-wrap.mjs +0 -62
  144. package/dist/lib/helpers/hooks.mjs +0 -389
  145. package/dist/lib/helpers/instance-manager.mjs +0 -111
  146. package/dist/lib/helpers/metadata-api.mjs +0 -201
  147. package/dist/lib/helpers/multidefault.mjs +0 -216
  148. package/dist/lib/modes/slothlet_eager.mjs +0 -126
  149. package/dist/lib/modes/slothlet_lazy.mjs +0 -513
  150. package/docs/API-RULES-CONDITIONS.md +0 -508
  151. package/types/dist/lib/engine/slothlet_child.d.mts +0 -2
  152. package/types/dist/lib/engine/slothlet_child.d.mts.map +0 -1
  153. package/types/dist/lib/engine/slothlet_engine.d.mts +0 -31
  154. package/types/dist/lib/engine/slothlet_engine.d.mts.map +0 -1
  155. package/types/dist/lib/engine/slothlet_esm.d.mts +0 -19
  156. package/types/dist/lib/engine/slothlet_esm.d.mts.map +0 -1
  157. package/types/dist/lib/engine/slothlet_helpers.d.mts +0 -25
  158. package/types/dist/lib/engine/slothlet_helpers.d.mts.map +0 -1
  159. package/types/dist/lib/engine/slothlet_worker.d.mts +0 -2
  160. package/types/dist/lib/engine/slothlet_worker.d.mts.map +0 -1
  161. package/types/dist/lib/helpers/als-eventemitter.d.mts +0 -56
  162. package/types/dist/lib/helpers/als-eventemitter.d.mts.map +0 -1
  163. package/types/dist/lib/helpers/api_builder/add_api.d.mts +0 -76
  164. package/types/dist/lib/helpers/api_builder/add_api.d.mts.map +0 -1
  165. package/types/dist/lib/helpers/api_builder/analysis.d.mts +0 -189
  166. package/types/dist/lib/helpers/api_builder/analysis.d.mts.map +0 -1
  167. package/types/dist/lib/helpers/api_builder/construction.d.mts +0 -107
  168. package/types/dist/lib/helpers/api_builder/construction.d.mts.map +0 -1
  169. package/types/dist/lib/helpers/api_builder/decisions.d.mts +0 -213
  170. package/types/dist/lib/helpers/api_builder/decisions.d.mts.map +0 -1
  171. package/types/dist/lib/helpers/api_builder/metadata.d.mts +0 -99
  172. package/types/dist/lib/helpers/api_builder/metadata.d.mts.map +0 -1
  173. package/types/dist/lib/helpers/api_builder.d.mts +0 -6
  174. package/types/dist/lib/helpers/api_builder.d.mts.map +0 -1
  175. package/types/dist/lib/helpers/auto-wrap.d.mts +0 -49
  176. package/types/dist/lib/helpers/auto-wrap.d.mts.map +0 -1
  177. package/types/dist/lib/helpers/hooks.d.mts +0 -342
  178. package/types/dist/lib/helpers/hooks.d.mts.map +0 -1
  179. package/types/dist/lib/helpers/instance-manager.d.mts +0 -41
  180. package/types/dist/lib/helpers/instance-manager.d.mts.map +0 -1
  181. package/types/dist/lib/helpers/metadata-api.d.mts +0 -132
  182. package/types/dist/lib/helpers/metadata-api.d.mts.map +0 -1
  183. package/types/dist/lib/helpers/multidefault.d.mts +0 -90
  184. package/types/dist/lib/helpers/multidefault.d.mts.map +0 -1
  185. package/types/dist/lib/modes/slothlet_eager.d.mts +0 -65
  186. package/types/dist/lib/modes/slothlet_eager.d.mts.map +0 -1
  187. package/types/dist/lib/modes/slothlet_lazy.d.mts +0 -31
  188. package/types/dist/lib/modes/slothlet_lazy.d.mts.map +0 -1
@@ -1,99 +0,0 @@
1
- /**
2
- * @Project: @cldmv/slothlet
3
- * @Filename: /src/lib/helpers/api_builder/metadata.mjs
4
- * @Date: 2025-12-31 00:00:00 -08:00
5
- * @Author: Nate Hyson <CLDMV>
6
- * @Email: <Shinrai@users.noreply.github.com>
7
- * -----
8
- * @Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
9
- * @Last modified time: 2025-12-31 22:30:16 -08:00 (1767249016)
10
- * -----
11
- * @Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
12
- */
13
- /**
14
- * @fileoverview Metadata management utilities for API functions.
15
- * @module @cldmv/slothlet/lib/helpers/api_builder/metadata
16
- * @memberof module:@cldmv/slothlet.lib.helpers.api_builder
17
- * @internal
18
- * @private
19
- *
20
- * @description
21
- * Provides utilities for tagging functions with immutable metadata, cleaning stale metadata
22
- * from cached modules, and creating immutable metadata objects with deep freezing.
23
- *
24
- * Key Features:
25
- * - Immutable metadata with Proxy-based enforcement
26
- * - Deep freezing of nested objects and arrays
27
- * - Recursive traversal for tagging/cleaning object trees
28
- * - CommonJS cache-aware metadata cleanup
29
- */
30
- /**
31
- * Creates an immutable-but-extensible metadata proxy object.
32
- *
33
- * @function createImmutableMetadata
34
- * @param {object} initial - Initial metadata properties
35
- * @returns {object} Object with immutable existing properties but allows adding new ones
36
- *
37
- * @description
38
- * Creates an object that enforces immutability of existing properties while allowing
39
- * new properties to be added. This prevents tampering with security-critical metadata
40
- * while allowing runtime extension of metadata for additional context.
41
- *
42
- * Security features:
43
- * - Existing properties cannot be modified (non-writable, non-configurable after first set)
44
- * - Properties cannot be deleted
45
- * - New properties can be added, which then become immutable
46
- *
47
- * @example
48
- * const meta = createImmutableMetadata({ trusted: true, version: "1.0" });
49
- * meta.author = "Alice"; // OK - new property
50
- * meta.author = "Bob"; // FAIL - cannot modify after setting
51
- * meta.trusted = false; // FAIL - cannot modify existing property
52
- * delete meta.version; // FAIL - cannot delete properties
53
- */
54
- export function createImmutableMetadata(initial?: object): object;
55
- /**
56
- * Removes metadata from all functions in an object tree.
57
- *
58
- * @function cleanMetadata
59
- * @param {object|Function} obj - Object or function to clean
60
- * @param {WeakSet} [visited] - Visited objects tracker to prevent infinite recursion
61
- * @returns {void}
62
- *
63
- * @description
64
- * Traverses an object/function tree and removes __metadata and __sourceFolder properties.
65
- * This is needed when reloading CommonJS modules that cache function object references.
66
- */
67
- export function cleanMetadata(obj: object | Function, visited?: WeakSet<any>): void;
68
- /**
69
- * Recursively tags all functions in an object tree with metadata.
70
- *
71
- * @function tagLoadedFunctions
72
- * @param {object|Function} obj - Object or function to tag
73
- * @param {object} metadata - Metadata object to attach
74
- * @param {string} baseDir - Base directory path for relative file tracking
75
- * @param {WeakSet} [visited] - Visited objects tracker to prevent infinite recursion
76
- * @returns {void}
77
- *
78
- * @description
79
- * Traverses an object/function tree and attaches immutable metadata to all functions.
80
- * Also tracks source file information (__sourceFile, __sourceLine) for stack trace
81
- * matching. Only tags functions that don't already have metadata (non-overwriting).
82
- *
83
- * Attached properties:
84
- * - __metadata: Immutable metadata proxy with all user-provided metadata
85
- * - __sourceFolder: Absolute path to the folder the module was loaded from
86
- * - __sourceFile: Absolute file path (for stack trace matching)
87
- * - __sourceLine: Line number where function is defined (for stack trace matching)
88
- *
89
- * @example
90
- * const modules = { math: { add: (a, b) => a + b } };
91
- * tagLoadedFunctions(modules, {
92
- * trusted: true,
93
- * version: "1.0.0",
94
- * author: "Alice"
95
- * }, "/path/to/plugins");
96
- * // Now modules.math.add.__metadata.trusted === true
97
- */
98
- export function tagLoadedFunctions(obj: object | Function, metadata: object, baseDir: string, visited?: WeakSet<any>): void;
99
- //# sourceMappingURL=metadata.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"metadata.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/metadata.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,kDApBW,MAAM,GACJ,MAAM,CAmJlB;AAED;;;;;;;;;;;GAWG;AACH,mCARW,MAAM,WAAS,2BAEb,IAAI,CAyChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wCA1BW,MAAM,WAAS,YACf,MAAM,WACN,MAAM,2BAEJ,IAAI,CA+EhB"}
@@ -1,6 +0,0 @@
1
- export { addApiFromFolder } from "@cldmv/slothlet/helpers/api_builder/add_api";
2
- export { isLikelySerializable, analyzeModule, processModuleFromAnalysis, analyzeDirectoryStructure, getCategoryBuildingDecisions } from "@cldmv/slothlet/helpers/api_builder/analysis";
3
- export { getFlatteningDecision, applyFunctionNamePreference, processModuleForAPI, buildCategoryDecisions } from "@cldmv/slothlet/helpers/api_builder/decisions";
4
- export { buildCategoryStructure, buildRootAPI, toapiPathKey, shouldIncludeFile } from "@cldmv/slothlet/helpers/api_builder/construction";
5
- export { safeDefine, deepMerge, mutateLiveBindingFunction } from "@cldmv/slothlet/helpers/utilities";
6
- //# sourceMappingURL=api_builder.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/api_builder.mjs"],"names":[],"mappings":""}
@@ -1,49 +0,0 @@
1
- /**
2
- * @Project: @cldmv/slothlet
3
- * @Filename: /src/lib/helpers/auto-wrap.mjs
4
- * @Date: 2025-10-21 13:32:36 -07:00 (1761078756)
5
- * @Author: Nate Hyson <CLDMV>
6
- * @Email: <Shinrai@users.noreply.github.com>
7
- * -----
8
- * @Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
9
- * @Last modified time: 2025-10-22 06:59:17 -07:00 (1761141557)
10
- * -----
11
- * @Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
12
- */
13
- /**
14
- * @fileoverview Helper for automatically wrapping Node.js EventEmitter instances within API modules.
15
- * Internal file (not exported in package.json).
16
- * @module @cldmv/slothlet/src/lib/helpers/auto-wrap
17
- */
18
- /**
19
- * Automatically wrap Node.js EventEmitter constructors when called within slothlet API context.
20
- * This ensures that EventEmitter instances created inside API modules preserve AsyncLocalStorage context.
21
- * @function autoWrapEventEmitters
22
- * @package
23
- * @param {NetModule} nodeModule - The Node.js module to wrap (e.g., require("node:net"))
24
- * @returns {NetModule} Wrapped module with auto-wrapping constructors
25
- *
26
- * @description
27
- * Wraps Node.js module functions that return EventEmitter instances so they automatically
28
- * return wrapped instances when called within slothlet API context.
29
- *
30
- * @example
31
- * // Usage in API modules:
32
- * import { autoWrapEventEmitters } from "@cldmv/slothlet/src/lib/helpers/auto-wrap";
33
- * import originalNet from "node:net";
34
- * const net = autoWrapEventEmitters(originalNet);
35
- * // Now net.createServer() returns wrapped instances automatically
36
- */
37
- export function autoWrapEventEmitters(nodeModule: NetModule): NetModule;
38
- /**
39
- * Lazily get the pre-wrapped net module for convenient use in API modules.
40
- * @function getNet
41
- * @package
42
- * @returns {Promise<NetModule>} Promise resolving to the wrapped net module
43
- * @example
44
- * const net = await getNet();
45
- */
46
- export function getNet(): Promise<NetModule>;
47
- export type NetModule = typeof import("node:net");
48
- export type NetServer = import("node:net").Server;
49
- //# sourceMappingURL=auto-wrap.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"auto-wrap.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/auto-wrap.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAdW,SAAS,GACP,SAAS,CA6CrB;AAED;;;;;;;GAOG;AACH,0BAJa,OAAO,CAAC,SAAS,CAAC,CAO9B;wBAGY,cAAc,UAAU,CAAC;wBACzB,OAAO,UAAU,EAAE,MAAM"}
@@ -1,342 +0,0 @@
1
- /**
2
- * @class HookManager
3
- * @internal
4
- * @private
5
- *
6
- * @description
7
- * Manages registration, pattern matching, and execution of hooks for slothlet API calls.
8
- * Hooks are executed in priority order (higher priority first), then registration order.
9
- *
10
- * @example
11
- * // Create hook manager
12
- * const manager = new HookManager();
13
- * manager.on("logger", "before", (ctx) => { console.log(ctx.path); });
14
- */
15
- export class HookManager {
16
- /**
17
- * @constructor
18
- * @param {boolean} [enabled=true] - Initial enabled state
19
- * @param {string} [defaultPattern="**"] - Default pattern for filtering
20
- * @param {object} [options={}] - Additional options
21
- * @param {boolean} [options.suppressErrors=false] - If true, errors are logged but not thrown (except for before/after hooks)
22
- */
23
- constructor(enabled?: boolean, defaultPattern?: string, options?: {
24
- suppressErrors?: boolean;
25
- });
26
- enabled: boolean;
27
- defaultPattern: string;
28
- suppressErrors: boolean;
29
- hooks: Map<any, any>;
30
- registrationOrder: number;
31
- reportedErrors: WeakSet<object>;
32
- /**
33
- * @function on
34
- * @public
35
- * @param {string} name - Hook name/ID for debugging and removal
36
- * @param {string} type - Hook type: "before", "after", "always", or "error"
37
- * @param {Function} handler - Hook handler function with type-specific signature:
38
- * - before: ({ path, args }) => modified args array or value to short-circuit
39
- * - after: ({ path, result }) => transformed result
40
- * - always: ({ path, result, hasError, errors }) => void (read-only)
41
- * - error: ({ path, error, errorType, source }) => void (observer)
42
- * @param {object} [options] - Registration options
43
- * @param {number} [options.priority=100] - Execution priority (higher = earlier)
44
- * @param {string} [options.pattern] - Glob pattern for path filtering
45
- * @returns {string} Hook name/ID for later removal
46
- *
47
- * @description
48
- * Register a hook with optional priority and pattern filtering.
49
- *
50
- * @example
51
- * // Register hook with priority
52
- * manager.on("validator", "before", handler, { priority: 200 });
53
- */
54
- public on(name: string, type: string, handler: Function, options?: {
55
- priority?: number;
56
- pattern?: string;
57
- }): string;
58
- /**
59
- * Clean up all hooks and resources
60
- * @public
61
- * @description
62
- * Clears all registered hooks and resets internal state.
63
- * Should be called during shutdown to prevent memory leaks.
64
- *
65
- * @example
66
- * // Clean up during shutdown
67
- * manager.cleanup();
68
- */
69
- public cleanup(): void;
70
- /**
71
- * @function off
72
- * @public
73
- * @param {string} nameOrPattern - Hook name or glob pattern to remove
74
- * @returns {boolean} True if one or more hooks were removed
75
- *
76
- * @description
77
- * Remove registered hook(s) by exact name or pattern matching.
78
- *
79
- * @example
80
- * // Remove hook by exact name
81
- * manager.off("validator");
82
- *
83
- * @example
84
- * // Remove all hooks matching pattern
85
- * manager.off("math.*");
86
- */
87
- public off(nameOrPattern: string): boolean;
88
- /**
89
- * @function clear
90
- * @public
91
- * @param {string} [type] - Optional hook type to clear ("before", "after", "always", "error")
92
- * @returns {void}
93
- *
94
- * @description
95
- * Remove registered hooks. If type is provided, only hooks of that type are removed.
96
- *
97
- * @example
98
- * // Clear all hooks
99
- * manager.clear();
100
- *
101
- * @example
102
- * // Clear only before hooks
103
- * manager.clear("before");
104
- */
105
- public clear(type?: string): void;
106
- /**
107
- * @function list
108
- * @public
109
- * @param {string} [type] - Optional hook type to filter by ("before", "after", "always", "error")
110
- * @returns {Array<object>} Array of hook metadata
111
- *
112
- * @description
113
- * List registered hooks with their metadata. When type is provided, only hooks
114
- * matching that type are returned.
115
- *
116
- * @example
117
- * // List all hooks
118
- * const hooks = manager.list();
119
- *
120
- * @example
121
- * // List only before hooks
122
- * const beforeHooks = manager.list("before");
123
- */
124
- public list(type?: string): Array<object>;
125
- /**
126
- * @function enable
127
- * @public
128
- * @param {string} [pattern] - Optional new default pattern
129
- * @returns {void}
130
- *
131
- * @description
132
- * Enable hook execution, optionally updating default pattern.
133
- *
134
- * @example
135
- * // Enable with new pattern
136
- * manager.enable("database.*");
137
- */
138
- public enable(pattern?: string): void;
139
- /**
140
- * @function disable
141
- * @public
142
- * @returns {void}
143
- *
144
- * @description
145
- * Disable hook execution (fast-path bypass).
146
- *
147
- * @example
148
- * // Disable hooks
149
- * manager.disable();
150
- */
151
- public disable(): void;
152
- /**
153
- * @function executeBeforeHooks
154
- * @internal
155
- * @private
156
- * @param {string} path - Function path (e.g., "database.users.create")
157
- * @param {Array} args - Function arguments
158
- * @returns {{cancelled: boolean, value?: any, args: Array}} Execution result
159
- *
160
- * @description
161
- * Execute before hooks in priority order. Returns object indicating if execution
162
- * should be cancelled (short-circuited) and potentially modified arguments.
163
- *
164
- * Hook return semantics:
165
- * - undefined: continue to next hook/function
166
- * - Array: modified arguments for next hook/function
167
- * - Other value: short-circuit and return this value
168
- *
169
- * @example
170
- * // Execute before hooks
171
- * const result = manager.executeBeforeHooks("database.users.create", [data]);
172
- * if (result.cancelled) return result.value;
173
- */
174
- private executeBeforeHooks;
175
- /**
176
- * @function executeAfterHooks
177
- * @internal
178
- * @private
179
- * @param {string} path - Function path
180
- * @param {any} initialResult - Initial result from function
181
- * @returns {any} Transformed result
182
- *
183
- * @description
184
- * Execute after hooks in priority order, chaining results through each hook.
185
- * Each hook receives the previous hook's return value (or initial result).
186
- * After hooks only run if the function actually executed (not short-circuited).
187
- *
188
- * @example
189
- * // Execute after hooks with chaining
190
- * const finalResult = manager.executeAfterHooks("database.users.create", result);
191
- */
192
- private executeAfterHooks;
193
- /**
194
- * @function executeAlwaysHooks
195
- * @internal
196
- * @private
197
- * @param {string} path - Function path
198
- * @param {any} result - Final result (from function or short-circuit)
199
- * @param {Array<Error>} [errors=[]] - Array of errors that occurred during execution
200
- * @returns {void}
201
- *
202
- * @description
203
- * Execute always hooks (like finally blocks). These hooks always run regardless
204
- * of whether execution was short-circuited, completed normally, or threw errors.
205
- * Always hooks receive full execution context including both errors and results,
206
- * allowing a single hook to handle all logging scenarios.
207
- *
208
- * @example
209
- * // Execute always hooks with success result
210
- * manager.executeAlwaysHooks("database.users.create", result, []);
211
- *
212
- * @example
213
- * // Execute always hooks with error context
214
- * manager.executeAlwaysHooks("database.users.create", undefined, [error]);
215
- */
216
- private executeAlwaysHooks;
217
- /**
218
- * @function executeErrorHooks
219
- * @internal
220
- * @private
221
- * @param {string} path - Function path
222
- * @param {Error} error - Error that was thrown
223
- * @param {Object} [source] - Source information about where error originated
224
- * @param {string} source.type - Source type: 'before', 'function', 'after', 'always'
225
- * @param {string} [source.hookId] - Hook ID if error came from a hook
226
- * @param {string} [source.hookTag] - Hook tag if error came from a hook
227
- * @returns {void}
228
- *
229
- * @description
230
- * Execute error hooks (observers only, errors bubble naturally).
231
- * Provides detailed context about where the error originated.
232
- *
233
- * @example
234
- * // Execute error hooks with source info
235
- * manager.executeErrorHooks("database.users.create", error, {
236
- * type: 'before',
237
- * hookId: 'hook-123',
238
- * hookTag: 'validation'
239
- * });
240
- */
241
- private executeErrorHooks;
242
- /**
243
- * @function _getMatchingHooks
244
- * @internal
245
- * @private
246
- * @param {string} type - Hook type to match
247
- * @param {string} path - Function path to test against patterns
248
- * @returns {Array<object>} Sorted array of matching hooks
249
- *
250
- * @description
251
- * Get hooks matching type and path, sorted by priority (DESC) then order (ASC).
252
- *
253
- * @example
254
- * // Get matching hooks
255
- * const hooks = manager._getMatchingHooks("before", "database.users.create");
256
- */
257
- private _getMatchingHooks;
258
- /**
259
- * @function _compilePattern
260
- * @internal
261
- * @private
262
- * @param {string} pattern - Glob pattern string
263
- * @returns {RegExp|null} Compiled RegExp or null for negation patterns
264
- *
265
- * @description
266
- * Compile glob pattern to RegExp with support for:
267
- * - `*`: single-level wildcard
268
- * - `**`: multi-level wildcard
269
- * - `{users,posts}`: brace expansion (max 10 nesting levels)
270
- * - `!internal.*`: negation patterns
271
- *
272
- * @example
273
- * // Compile pattern
274
- * const regex = manager._compilePattern("database.*.create");
275
- */
276
- private _compilePattern;
277
- /**
278
- * @function _expandBraces
279
- * @internal
280
- * @private
281
- * @param {string} pattern - Pattern with potential braces
282
- * @param {number} [depth=0] - Current nesting depth
283
- * @returns {Array<string>} Expanded pattern alternatives
284
- *
285
- * @description
286
- * Expand brace patterns like `{users,posts}` to multiple alternatives.
287
- * Limits nesting to MAX_BRACE_NESTING to prevent performance issues.
288
- *
289
- * @example
290
- * // Expand braces
291
- * const patterns = manager._expandBraces("{users,posts}.create");
292
- * // Returns: ["users.create", "posts.create"]
293
- */
294
- private _expandBraces;
295
- /**
296
- * @function _splitAlternatives
297
- * @internal
298
- * @private
299
- * @param {string} str - String to split on commas
300
- * @returns {Array<string>} Split alternatives
301
- *
302
- * @description
303
- * Split brace content on commas, respecting nested braces.
304
- *
305
- * @example
306
- * // Split alternatives
307
- * const alts = manager._splitAlternatives("users,posts,{admin,guest}");
308
- */
309
- private _splitAlternatives;
310
- /**
311
- * @function _patternToRegex
312
- * @internal
313
- * @private
314
- * @param {string} pattern - Pattern without braces
315
- * @returns {string} Regex pattern string
316
- *
317
- * @description
318
- * Convert glob pattern to regex pattern string.
319
- *
320
- * @example
321
- * // Convert pattern
322
- * const regex = manager._patternToRegex("database.*.create");
323
- */
324
- private _patternToRegex;
325
- /**
326
- * @function _matchPattern
327
- * @internal
328
- * @private
329
- * @param {RegExp|object} compiledPattern - Compiled pattern or negation object
330
- * @param {string} path - Path to test
331
- * @returns {boolean} True if path matches pattern
332
- *
333
- * @description
334
- * Test if path matches compiled pattern, handling negation.
335
- *
336
- * @example
337
- * // Match pattern
338
- * const matches = manager._matchPattern(compiledPattern, "database.users.create");
339
- */
340
- private _matchPattern;
341
- }
342
- //# sourceMappingURL=hooks.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"hooks.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/hooks.mjs"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;GAaG;AACH;IACC;;;;;;OAMG;IACH,sBALW,OAAO,mBACP,MAAM,YAEd;QAA0B,cAAc,GAAhC,OAAO;KACjB,EAQA;IANA,iBAAsB;IACtB,uBAAoC;IACpC,wBAAqD;IACrD,qBAAsB;IACtB,0BAA0B;IAC1B,gCAAmC;IAGpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAnBW,MAAM,QACN,MAAM,+BAOd;QAAyB,QAAQ,GAAzB,MAAM;QACW,OAAO,GAAxB,MAAM;KACd,GAAU,MAAM,CA0BlB;IAED;;;;;;;;;;OAUG;IACH,uBAKC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,0BAdW,MAAM,GACJ,OAAO,CA6BnB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,oBAdW,MAAM,GACJ,IAAI,CA0BhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAfW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CA4BzB;IAED;;;;;;;;;;;;OAYG;IACH,wBAVW,MAAM,GACJ,IAAI,CAchB;IAED;;;;;;;;;;;OAWG;IACH,kBATa,IAAI,CAWhB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,2BAkCC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,0BAwBC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,2BAqBC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,0BAyBC;IAED;;;;;;;;;;;;;;OAcG;IACH,0BAkBC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAmBC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBA4CC;IAED;;;;;;;;;;;;;OAaG;IACH,2BAuBC;IAED;;;;;;;;;;;;;OAaG;IACH,wBAiBC;IAED;;;;;;;;;;;;;;OAcG;IACH,sBAOC;CACD"}
@@ -1,41 +0,0 @@
1
- /**
2
- * Get instance data by ID
3
- * @param {string} instanceId - Instance identifier
4
- * @returns {object|null} Instance data or null if not found
5
- */
6
- export function getInstanceData(instanceId: string): object | null;
7
- /**
8
- * Update instance data for a specific key
9
- * @param {string} instanceId - Instance identifier
10
- * @param {string} key - Data key (self, context, reference)
11
- * @param {any} value - Data value
12
- * @returns {void}
13
- */
14
- export function updateInstanceData(instanceId: string, key: string, value: any): void;
15
- /**
16
- * Clean up instance data when no longer needed
17
- * @param {string} instanceId - Instance identifier
18
- * @returns {Promise<void>}
19
- */
20
- export function cleanupInstance(instanceId: string): Promise<void>;
21
- /**
22
- * Set the currently active instance (called during module loading)
23
- * @param {string|null} instanceId - Instance ID to set as active
24
- */
25
- export function setActiveInstance(instanceId: string | null): void;
26
- /**
27
- * Get the current active instance ID
28
- * @returns {string|null} Current active instance ID
29
- */
30
- export function getCurrentActiveInstanceId(): string | null;
31
- /**
32
- * Detect current instance ID from stack trace
33
- * @returns {string|null} Detected instance ID or null
34
- */
35
- export function detectCurrentInstanceId(): string | null;
36
- /**
37
- * Get all registered instance IDs
38
- * @returns {string[]} Array of instance IDs
39
- */
40
- export function getAllInstanceIds(): string[];
41
- //# sourceMappingURL=instance-manager.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"instance-manager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/instance-manager.mjs"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,4CAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAIvB;AAED;;;;;;GAMG;AACH,+CALW,MAAM,OACN,MAAM,SACN,GAAG,GACD,IAAI,CAqBhB;AAED;;;;GAIG;AACH,4CAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CASzB;AAED;;;GAGG;AACH,8CAFW,MAAM,GAAC,IAAI,QAKrB;AAED;;;GAGG;AACH,8CAFa,MAAM,GAAC,IAAI,CAIvB;AAED;;;GAGG;AACH,2CAFa,MAAM,GAAC,IAAI,CAkCvB;AAED;;;GAGG;AACH,qCAFa,MAAM,EAAE,CAIpB"}