@cldmv/slothlet 2.11.0 → 3.0.1

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 (189) hide show
  1. package/AGENT-USAGE.md +355 -325
  2. package/README.md +554 -238
  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 +123 -117
  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 +525 -744
  51. package/docs/API-RULES.md +338 -486
  52. package/index.cjs +4 -4
  53. package/index.mjs +82 -45
  54. package/package.json +143 -30
  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 +184 -111
  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 -553
  138. package/dist/lib/helpers/api_builder/analysis.mjs +0 -532
  139. package/dist/lib/helpers/api_builder/construction.mjs +0 -495
  140. package/dist/lib/helpers/api_builder/decisions.mjs +0 -748
  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 -154
  149. package/dist/lib/modes/slothlet_lazy.mjs +0 -594
  150. package/docs/API-RULES-CONDITIONS.md +0 -712
  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 -102
  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
  189. package/types/index.d.mts.map +0 -1
@@ -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"}
@@ -1,132 +0,0 @@
1
- export namespace metadataAPI {
2
- /**
3
- * Get metadata of the function that called the current function.
4
- *
5
- * @function caller
6
- * @memberof metadataAPI
7
- * @returns {object|null} Caller's metadata object or null if not found
8
- * @public
9
- *
10
- * @description
11
- * Uses stack trace analysis to identify the calling function and retrieve
12
- * its attached metadata. Useful for implementing access control where a
13
- * function needs to verify the identity/permissions of its caller.
14
- *
15
- * Stack trace structure:
16
- * - Line 0: Error
17
- * - Line 1: metadataAPI.caller (this function)
18
- * - Line 2: Current function (the one checking)
19
- * - Line 3: The caller we want to identify
20
- *
21
- * @example
22
- * // In a secure function
23
- * import { metadataAPI } from "@cldmv/slothlet/runtime";
24
- *
25
- * export function getSecrets() {
26
- * const caller = metadataAPI.caller();
27
- *
28
- * if (!caller?.trusted) {
29
- * throw new Error("Access denied: untrusted caller");
30
- * }
31
- *
32
- * if (!caller.permissions?.includes("read_secrets")) {
33
- * throw new Error("Access denied: insufficient permissions");
34
- * }
35
- *
36
- * return { apiKey: "secret123", token: "xyz" };
37
- * }
38
- *
39
- * @example
40
- * // With custom metadata tags
41
- * const caller = metadataAPI.caller();
42
- * console.log("Caller source:", caller?.sourceFolder);
43
- * console.log("Caller version:", caller?.version);
44
- * console.log("Caller author:", caller?.author);
45
- */
46
- function caller(): object | null;
47
- /**
48
- * Get metadata of the current function.
49
- *
50
- * @function self
51
- * @memberof metadataAPI
52
- * @returns {object|null} Current function's metadata or null if not found
53
- * @public
54
- *
55
- * @description
56
- * Retrieves metadata attached to the currently executing function. Useful
57
- * for functions that need to inspect their own metadata (e.g., for logging,
58
- * conditional behavior based on load source).
59
- *
60
- * Stack trace structure:
61
- * - Line 0: Error
62
- * - Line 1: metadataAPI.self (this function)
63
- * - Line 2: Current function (the one we want to identify)
64
- *
65
- * @example
66
- * // Function checking its own metadata
67
- * import { metadataAPI } from "@cldmv/slothlet/runtime";
68
- *
69
- * export function smartFunction() {
70
- * const meta = metadataAPI.self();
71
- *
72
- * if (meta?.environment === "development") {
73
- * console.log("Running in development mode");
74
- * }
75
- *
76
- * if (meta?.version) {
77
- * console.log(`Function version: ${meta.version}`);
78
- * }
79
- *
80
- * return "result";
81
- * }
82
- */
83
- function self(): object | null;
84
- /**
85
- * Get metadata of any function by API path.
86
- *
87
- * @function get
88
- * @memberof metadataAPI
89
- * @param {string} path - Dot-notation API path (e.g., "math.add", "plugins.helper")
90
- * @param {object} [apiRoot] - Optional API root object (uses runtime.self if not provided)
91
- * @returns {object|null} Function's metadata or null if not found
92
- * @public
93
- *
94
- * @description
95
- * Retrieves metadata for any function in the API tree by its path. Useful
96
- * for checking metadata of functions you have references to, or for
97
- * administrative/introspection purposes.
98
- *
99
- * @example
100
- * // Check metadata of a specific function
101
- * import { metadataAPI } from "@cldmv/slothlet/runtime";
102
- *
103
- * export function checkPermissions() {
104
- * const pluginMeta = metadataAPI.get("plugins.userPlugin");
105
- *
106
- * if (!pluginMeta) {
107
- * throw new Error("Plugin not found or has no metadata");
108
- * }
109
- *
110
- * if (pluginMeta.trusted) {
111
- * console.log("Plugin is trusted");
112
- * } else {
113
- * console.log("Plugin is untrusted");
114
- * }
115
- * }
116
- *
117
- * @example
118
- * // Iterate and check all plugins
119
- * const pluginPaths = ["plugins.auth", "plugins.logger", "plugins.cache"];
120
- * for (const path of pluginPaths) {
121
- * const meta = metadataAPI.get(path);
122
- * console.log(`${path}: ${meta?.version || "unknown"}`);
123
- * }
124
- *
125
- * @example
126
- * // From outside slothlet context, pass API root explicitly
127
- * const api = await slothlet({ dir: "./modules" });
128
- * const meta = await metadataAPI.get("plugins.helper", api);
129
- */
130
- function get(path: string, apiRoot?: object): object | null;
131
- }
132
- //# sourceMappingURL=metadata-api.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"metadata-api.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/metadata-api.mjs"],"names":[],"mappings":";IAmNC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,mBAvCa,MAAM,GAAC,IAAI,CAgEvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,iBA/Ba,MAAM,GAAC,IAAI,CAsDvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,mBAzCW,MAAM,YACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAsDvB"}
@@ -1,90 +0,0 @@
1
- /**
2
- * Analyzes module files to detect multi-default and self-referential patterns.
3
- * @internal
4
- * @private
5
- * @param {Array<{name: string}>} moduleFiles - Array of module file objects with name property
6
- * @param {string} baseDir - Base directory path containing the modules
7
- * @param {object} [options={}] - Configuration options
8
- * @param {boolean} [options.debug=false] - Enable debug logging
9
- * @param {object|null} [options.instance=null] - Slothlet instance for cache isolation
10
- * @returns {Promise<{
11
- * totalDefaultExports: number,
12
- * hasMultipleDefaultExports: boolean,
13
- * selfReferentialFiles: Set<string>,
14
- * rawModuleCache: Map<string, object>,
15
- * defaultExportFiles: Array<{fileName: string, rawModule: object}>
16
- * }>} Analysis results
17
- * @example // Internal usage in slothlet modes
18
- * const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug: config.debug, instance });
19
- * if (analysis.hasMultipleDefaultExports) {
20
- * // Handle multi-default context
21
- * }
22
- */
23
- export function multidefault_analyzeModules(moduleFiles: Array<{
24
- name: string;
25
- }>, baseDir: string, options?: {
26
- debug?: boolean;
27
- instance?: object | null;
28
- }): Promise<{
29
- totalDefaultExports: number;
30
- hasMultipleDefaultExports: boolean;
31
- selfReferentialFiles: Set<string>;
32
- rawModuleCache: Map<string, object>;
33
- defaultExportFiles: Array<{
34
- fileName: string;
35
- rawModule: object;
36
- }>;
37
- }>;
38
- /**
39
- * Checks if a raw module's default export is self-referential (points to a named export).
40
- * @internal
41
- * @private
42
- * @param {object} rawModule - Raw module object to check
43
- * @returns {boolean} True if default export points to a named export
44
- * @example // Internal usage
45
- * const isSelfRef = multidefault_isSelfReferential(rawModule);
46
- */
47
- export function multidefault_isSelfReferential(rawModule: object): boolean;
48
- /**
49
- * Determines auto-flattening behavior based on multi-default context and module structure.
50
- * @internal
51
- * @private
52
- * @param {object} options - Configuration options
53
- * @param {boolean} options.hasMultipleDefaultExports - Whether multiple default exports exist
54
- * @param {boolean} options.moduleHasDefault - Whether current module has default export
55
- * @param {boolean} options.isSelfReferential - Whether current module is self-referential
56
- * @param {Array<string>} options.moduleKeys - Named export keys from the module
57
- * @param {string} options.apiPathKey - API key for the module
58
- * @param {number} options.totalModuleCount - Total number of modules in directory
59
- * @param {boolean} [options.debug=false] - Enable debug logging
60
- * @returns {{
61
- * shouldFlatten: boolean,
62
- * flattenToRoot: boolean,
63
- * preserveAsNamespace: boolean,
64
- * reason: string
65
- * }} Flattening decision and reasoning
66
- * @example // Internal usage in processing logic
67
- * const decision = multidefault_getFlatteningDecision({
68
- * hasMultipleDefaultExports: true,
69
- * moduleHasDefault: false,
70
- * isSelfReferential: false,
71
- * moduleKeys: ["add", "subtract"],
72
- * apiPathKey: "math",
73
- * totalModuleCount: 3
74
- * });
75
- */
76
- export function multidefault_getFlatteningDecision(options: {
77
- hasMultipleDefaultExports: boolean;
78
- moduleHasDefault: boolean;
79
- isSelfReferential: boolean;
80
- moduleKeys: Array<string>;
81
- apiPathKey: string;
82
- totalModuleCount: number;
83
- debug?: boolean;
84
- }): {
85
- shouldFlatten: boolean;
86
- flattenToRoot: boolean;
87
- preserveAsNamespace: boolean;
88
- reason: string;
89
- };
90
- //# sourceMappingURL=multidefault.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"multidefault.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/multidefault.mjs"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yDAlBW,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,WACrB,MAAM,YAEd;IAA0B,KAAK,GAAvB,OAAO;IACe,QAAQ,GAA9B,MAAM,GAAC,IAAI;CACnB,GAAU,OAAO,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yBAAyB,EAAE,OAAO,CAAC;IACnC,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kBAAkB,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACjE,CAAC,CAuGJ;AAED;;;;;;;;GAQG;AACH,0DALW,MAAM,GACJ,OAAO,CAWnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4DAvBG;IAAyB,yBAAyB,EAA1C,OAAO;IACU,gBAAgB,EAAjC,OAAO;IACU,iBAAiB,EAAlC,OAAO;IACgB,UAAU,EAAjC,KAAK,CAAC,MAAM,CAAC;IACG,UAAU,EAA1B,MAAM;IACU,gBAAgB,EAAhC,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU;IACR,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf,CA4FH"}
@@ -1,65 +0,0 @@
1
- /**
2
- * @function eager_wrapWithRunCtx
3
- * @internal
4
- * @package
5
- * @alias module:@cldmv/slothlet.modes.eager.eager_wrapWithRunCtx
6
- * @memberof module:@cldmv/slothlet.modes.eager
7
- * @param {*} obj - The object/function to wrap
8
- * @param {object} instance - The slothlet instance that will have boundapi.__ctx attached
9
- * @returns {*} The wrapped object/function
10
- *
11
- * @description
12
- * Recursively wraps all functions in an object with runWithCtx for eager mode.
13
- * This makes eager mode use the same call stack optimization as lazy mode.
14
- *
15
- * @example
16
- * // Wrapping a function
17
- * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
18
- *
19
- * @example
20
- * // Wrapping an object with nested functions
21
- * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
22
- *
23
- * @example
24
- * // Wrapping a function
25
- * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
26
- *
27
- * @example
28
- * // Wrapping an object with nested functions
29
- * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
30
- * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
31
- *
32
- * @example
33
- * // Wrapping an object with nested functions
34
- * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
35
- */
36
- /**
37
- * @function create
38
- * @internal
39
- * @package
40
- * @async
41
- * @alias module:@cldmv/slothlet.modes.eager.create
42
- * @memberof module:@cldmv/slothlet.modes.eager
43
- * @param {string} dir - Directory to load
44
- * @param {number} [maxDepth=Infinity] - Maximum depth to traverse
45
- * @param {number} [currentDepth=0] - Current traversal depth
46
- * @returns {Promise<object>} Complete API object with all modules loaded
47
- * @throws {Error} When module loading or directory traversal fails
48
- *
49
- * @description
50
- * Creates the eager API for slothlet (mode: eager).
51
- * Immediately loads all modules and constructs the complete API structure.
52
- *
53
- * @example
54
- * // Internal usage - called by slothlet core
55
- * const api = await create('./api_test', 3, 0);
56
- * // Returns: { math: { add: [Function], multiply: [Function] }, ... }
57
- *
58
- * @example
59
- * // Root-level processing with function exports
60
- * const api = await create('./api_test');
61
- * // If root has default function: api becomes that function with properties
62
- * // Otherwise: api is object with module properties
63
- */
64
- export function create(dir: string, maxDepth?: number, currentDepth?: number): Promise<object>;
65
- //# sourceMappingURL=slothlet_eager.d.mts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"slothlet_eager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_eager.mjs"],"names":[],"mappings":"AA4IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsDH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4BArBW,MAAM,aACN,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CA4I3B"}