navi-hey 1.9.2 → 1.11.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 (101) hide show
  1. package/README.md +3 -106
  2. package/bin/navi.js +2 -2
  3. package/config/menu.yml +36 -0
  4. package/lib/README.md +20 -0
  5. package/lib/common/utils/logging/{BufferedLogger.js → buffer/BufferedLogger.js} +5 -5
  6. package/lib/common/utils/logging/{LogBuffer.js → buffer/LogBuffer.js} +4 -4
  7. package/lib/common/utils/logging/{LogBufferCollection.js → buffer/LogBufferCollection.js} +2 -2
  8. package/lib/exceptions/config/ExtensionsDirectoryMissing.js +21 -0
  9. package/lib/exceptions/config/MenuConfigurationInvalid.js +23 -0
  10. package/lib/exceptions/config/{InvalidEmitBodyTemplate.js → emit/InvalidEmitBodyTemplate.js} +1 -1
  11. package/lib/exceptions/config/{InvalidEmitCooldown.js → emit/InvalidEmitCooldown.js} +1 -1
  12. package/lib/exceptions/config/{InvalidEmitHeaders.js → emit/InvalidEmitHeaders.js} +1 -1
  13. package/lib/exceptions/config/{InvalidEmitMethod.js → emit/InvalidEmitMethod.js} +1 -1
  14. package/lib/exceptions/config/{InvalidEmitRetries.js → emit/InvalidEmitRetries.js} +1 -1
  15. package/lib/exceptions/config/{MissingEmitUrl.js → emit/MissingEmitUrl.js} +1 -1
  16. package/lib/exceptions/config/{ConfigurationFileNotFound.js → file/ConfigurationFileNotFound.js} +1 -1
  17. package/lib/exceptions/config/{ConfigurationFileNotProvided.js → file/ConfigurationFileNotProvided.js} +1 -1
  18. package/lib/exceptions/config/{InvalidMemoryDataStore.js → memory/InvalidMemoryDataStore.js} +1 -1
  19. package/lib/exceptions/config/{InvalidMemoryThresholds.js → memory/InvalidMemoryThresholds.js} +1 -1
  20. package/lib/exceptions/config/{InvalidParserMatch.js → parser/InvalidParserMatch.js} +1 -1
  21. package/lib/exceptions/config/{InvalidParserType.js → parser/InvalidParserType.js} +1 -1
  22. package/lib/exceptions/config/{MissingParserField.js → parser/MissingParserField.js} +1 -1
  23. package/lib/exceptions/config/{MissingParserFields.js → parser/MissingParserFields.js} +1 -1
  24. package/lib/exceptions/config/{MissingParserMatch.js → parser/MissingParserMatch.js} +1 -1
  25. package/lib/models/configs/Config.js +1 -1
  26. package/lib/models/configs/MemoryConfig.js +2 -2
  27. package/lib/models/configs/MenuConfig.js +248 -0
  28. package/lib/models/configs/MenuEntry.js +127 -0
  29. package/lib/models/request/Resource.js +1 -1
  30. package/lib/models/request/{TemplateStringRenderer.js → renderers/TemplateStringRenderer.js} +1 -1
  31. package/lib/models/request/{ResourceRequest.js → resource_request/ResourceRequest.js} +7 -7
  32. package/lib/models/request/{ResourceRequestAction.js → resource_request/ResourceRequestAction.js} +5 -5
  33. package/lib/models/request/{ResourceRequestEmit.js → resource_request/ResourceRequestEmit.js} +9 -9
  34. package/lib/models/request/{ResourceRequestPaginatedAction.js → resource_request/ResourceRequestPaginatedAction.js} +7 -7
  35. package/lib/models/request/{ResourceRequestParser.js → resource_request/ResourceRequestParser.js} +1 -1
  36. package/lib/parsers/CssSelectorParser.js +2 -2
  37. package/lib/parsers/JsonPathParser.js +5 -7
  38. package/lib/parsers/css_selector_parser/FilterMatcher.js +1 -1
  39. package/lib/parsers/json_path/MatchResolver.js +28 -10
  40. package/lib/parsers/regex_parser/AttributesValidator.js +2 -2
  41. package/lib/registry/ClientRegistry.js +1 -1
  42. package/lib/registry/EmissionRegistry.js +1 -1
  43. package/lib/registry/ExtractionRegistry.js +1 -1
  44. package/lib/registry/LogRegistry.js +6 -6
  45. package/lib/registry/MemoryRegistry.js +1 -1
  46. package/lib/registry/ParserRegistry.js +1 -1
  47. package/lib/registry/ResourceRegistry.js +1 -1
  48. package/lib/registry/{EmissionRegistryInstance.js → instances/EmissionRegistryInstance.js} +5 -5
  49. package/lib/registry/{ExtractionRegistryInstance.js → instances/ExtractionRegistryInstance.js} +5 -5
  50. package/lib/registry/{LogRegistryInstance.js → instances/LogRegistryInstance.js} +10 -10
  51. package/lib/registry/{MemoryRegistryInstance.js → instances/MemoryRegistryInstance.js} +4 -4
  52. package/lib/registry/{NamedRegistry.js → namespace/NamedRegistry.js} +1 -1
  53. package/lib/registry/{Namespace.js → namespace/Namespace.js} +2 -2
  54. package/lib/registry/{NamespaceMap.js → namespace/NamespaceMap.js} +4 -4
  55. package/lib/serializers/LogSerializer.js +1 -1
  56. package/lib/serializers/MenuSerializer.js +19 -0
  57. package/lib/server/RouteRegister.js +1 -1
  58. package/lib/server/Router.js +73 -2
  59. package/lib/server/SecuredRequestHandler.js +1 -1
  60. package/lib/server/WebServer.js +9 -5
  61. package/lib/server/extensions/ExtensionModuleValidator.js +112 -0
  62. package/lib/server/extensions/ExtensionRoutesLoader.js +196 -0
  63. package/lib/server/extensions/ExtensionsEnv.js +52 -0
  64. package/lib/server/handlers/FrontendAssetsHandler.js +50 -0
  65. package/lib/server/handlers/FrontendManifestHandler.js +83 -0
  66. package/lib/server/handlers/LinksHandler.js +1 -1
  67. package/lib/server/handlers/MenuHandler.js +36 -0
  68. package/lib/server/handlers/api/ApiConfigHandler.js +1 -1
  69. package/lib/services/application/Application.js +3 -2
  70. package/lib/services/application/ApplicationConfigurator.js +8 -3
  71. package/lib/services/application/ApplicationInstance.js +21 -3
  72. package/lib/services/application/ArgumentsParser.js +9 -3
  73. package/lib/services/application/ConfigStore.js +12 -1
  74. package/lib/services/builders/NamespaceMapBuilder.js +2 -2
  75. package/lib/services/builders/RegistriesBuilder.js +1 -1
  76. package/lib/services/config/ConfigIncluder.js +3 -3
  77. package/lib/services/engine/EngineController.js +1 -1
  78. package/lib/services/engine/ServerController.js +8 -4
  79. package/lib/utils/ResourceEnqueuer.js +1 -1
  80. package/package.json +7 -1
  81. package/static/assets/{index-FbZXTjVy.css → index-CKnpQp0V.css} +1 -1
  82. package/static/assets/index-D9DOeCyI.js +49 -0
  83. package/static/assets/react-vendor.js +11 -0
  84. package/static/index.html +16 -2
  85. package/lib/utils/index.js +0 -2
  86. package/lib/utils/logging/BaseLogger.js +0 -1
  87. package/lib/utils/logging/BufferedLogger.js +0 -1
  88. package/lib/utils/logging/ConsoleLogger.js +0 -1
  89. package/lib/utils/logging/Log.js +0 -1
  90. package/lib/utils/logging/LogBuffer.js +0 -1
  91. package/lib/utils/logging/LogBufferCollection.js +0 -1
  92. package/lib/utils/logging/LogContext.js +0 -1
  93. package/lib/utils/logging/LogFactory.js +0 -1
  94. package/lib/utils/logging/LogFilter.js +0 -1
  95. package/lib/utils/logging/Logger.js +0 -1
  96. package/lib/utils/logging/LoggerGroup.js +0 -1
  97. package/static/assets/index-C7P-w9r_.js +0 -59
  98. /package/lib/exceptions/config/{ConfigurationIncludeNotFound.js → file/ConfigurationIncludeNotFound.js} +0 -0
  99. /package/lib/models/request/{BodyTemplateRenderer.js → renderers/BodyTemplateRenderer.js} +0 -0
  100. /package/lib/models/request/{TokenResolver.js → tokens/TokenResolver.js} +0 -0
  101. /package/lib/models/request/{UrlTokenResolver.js → tokens/UrlTokenResolver.js} +0 -0
@@ -0,0 +1,248 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import YAML from 'yaml';
3
+ import { MenuEntry } from './MenuEntry.js';
4
+ import { EnvStringResolver } from '../../common/utils/env_resolver/EnvStringResolver.js';
5
+ import { Logger } from '../../common/utils/logging/Logger.js';
6
+ import { MenuConfigurationInvalid } from '../../exceptions/config/MenuConfigurationInvalid.js';
7
+
8
+ const DEFAULT_LABELS = {
9
+ '/logs': 'Logs',
10
+ '/memory/status': 'Memory',
11
+ };
12
+
13
+ /**
14
+ * Loads and validates the internal navigation menu configuration file into a
15
+ * list of {@link MenuEntry} instances.
16
+ *
17
+ * Behaviour (see the IMPL-2 shared contract):
18
+ * - Missing / empty / whitespace-only file, or a document carrying neither an
19
+ * `entries` nor a `defaults` key, falls back to
20
+ * {@link MenuConfig.DEFAULT_ENTRIES}.
21
+ * - Operator `entries` are merged after the shipped default block; an explicit
22
+ * `entries: []` merges an empty custom list (defaults still render).
23
+ * - A top-level `defaults: false` empties the shipped default block; a
24
+ * non-boolean `defaults` is ignored with a `Logger.warn` and treated as `true`.
25
+ * - `hidden: true` on a known default route suppresses that default; on any
26
+ * other route the route is retained and reported through `/menu.json`'s
27
+ * `hidden` list (as a {@link MenuEntry} flagged `hidden`) so the SPA can
28
+ * filter extension routes against it.
29
+ * - A non-hidden custom entry re-listing a known default route repositions that
30
+ * default to the custom file position (its `text`, or the shipped label when
31
+ * omitted).
32
+ * - Duplicate routes in the merged render list are dropped first-wins with a
33
+ * `Logger.warn`.
34
+ * - A YAML parse failure, or an `entries` value that is present but not a list,
35
+ * throws {@link MenuConfigurationInvalid} (fail-fast at startup).
36
+ * - Individual malformed entries are dropped with a `Logger.warn`.
37
+ * @author darthjee
38
+ */
39
+ class MenuConfig {
40
+ /**
41
+ * In-code fallback used when the menu file is absent or empty.
42
+ * @returns {Array<MenuEntry>} The default Logs + Memory menu.
43
+ */
44
+ static get DEFAULT_ENTRIES() {
45
+ return [
46
+ new MenuEntry({ route: '/logs', text: 'Logs' }),
47
+ new MenuEntry({ route: '/memory/status', text: 'Memory' }),
48
+ ];
49
+ }
50
+
51
+ /**
52
+ * Routes that identify a shipped default entry.
53
+ * @returns {Array<string>} The known default routes, in shipped order.
54
+ */
55
+ static get DEFAULT_ROUTES() {
56
+ return this.DEFAULT_ENTRIES.map((entry) => entry.route);
57
+ }
58
+
59
+ /**
60
+ * Maps a known default `route` to its shipped display label so a bare
61
+ * re-list can restore it.
62
+ * @param {string} route - A route value.
63
+ * @returns {(string|undefined)} The shipped label, or undefined when the
64
+ * route is not a known default.
65
+ */
66
+ static defaultLabel(route) {
67
+ return DEFAULT_LABELS[route];
68
+ }
69
+
70
+ /**
71
+ * Loads the menu entries from the given file path.
72
+ * @param {string} path - Path to the menu configuration file.
73
+ * @returns {Array<MenuEntry>} The resolved menu entries, in render order.
74
+ * @throws {MenuConfigurationInvalid} On an unparseable file or a non-list `entries`.
75
+ */
76
+ static fromFile(path) {
77
+ if (!existsSync(path)) return this.DEFAULT_ENTRIES;
78
+
79
+ const content = readFileSync(path, 'utf8');
80
+ if (content.trim() === '') return this.DEFAULT_ENTRIES;
81
+
82
+ const parsed = this.#parse(path, content);
83
+
84
+ if (parsed === null || typeof parsed !== 'object') {
85
+ return this.DEFAULT_ENTRIES;
86
+ }
87
+
88
+ const hasEntries = 'entries' in parsed;
89
+ const hasDefaults = 'defaults' in parsed;
90
+
91
+ if (!hasEntries && !hasDefaults) {
92
+ return this.DEFAULT_ENTRIES;
93
+ }
94
+
95
+ if (hasEntries && !Array.isArray(parsed.entries)) {
96
+ throw new MenuConfigurationInvalid(path, '"entries" must be a list');
97
+ }
98
+
99
+ const defaultBlock = this.#resolveDefaultBlock(parsed);
100
+ const rawEntries = hasEntries ? parsed.entries : [];
101
+
102
+ return this.#resolve(defaultBlock, rawEntries);
103
+ }
104
+
105
+ /**
106
+ * Resolves env vars and YAML-parses the file content.
107
+ * @param {string} path - The file path (for the exception message).
108
+ * @param {string} content - The raw file content.
109
+ * @returns {*} The parsed document.
110
+ * @throws {MenuConfigurationInvalid} When parsing fails.
111
+ */
112
+ static #parse(path, content) {
113
+ try {
114
+ const resolved = new EnvStringResolver(content).resolve();
115
+ return YAML.parse(resolved);
116
+ } catch (error) {
117
+ throw new MenuConfigurationInvalid(path, error.message);
118
+ }
119
+ }
120
+
121
+ /**
122
+ * Resolves the shipped default block from the top-level `defaults` key.
123
+ * @param {object} parsed - The parsed menu document.
124
+ * @returns {Array<MenuEntry>} The shipped default block for this load.
125
+ */
126
+ static #resolveDefaultBlock(parsed) {
127
+ if (!('defaults' in parsed)) return this.DEFAULT_ENTRIES;
128
+
129
+ const { defaults } = parsed;
130
+
131
+ if (defaults === false) return [];
132
+ if (defaults === true) return this.DEFAULT_ENTRIES;
133
+
134
+ Logger.warn('[menu] ignoring non-boolean "defaults" value; treating as true');
135
+ return this.DEFAULT_ENTRIES;
136
+ }
137
+
138
+ /**
139
+ * Runs the full SPEC-2 resolution pipeline: validate, partition `hidden`,
140
+ * reposition re-listed defaults, merge, then first-wins de-dup.
141
+ * @param {Array<MenuEntry>} defaultBlock - The shipped default block.
142
+ * @param {Array<*>} rawEntries - The raw `entries` list.
143
+ * @returns {Array<MenuEntry>} The resolved menu entries, in render order.
144
+ */
145
+ static #resolve(defaultBlock, rawEntries) {
146
+ const valid = this.#collectValid(rawEntries);
147
+ const { suppressed, visible, hiddenRoutes } = this.#partitionHidden(valid);
148
+ const repositioned = new Set(
149
+ visible.map((raw) => raw.route).filter((route) => this.DEFAULT_ROUTES.includes(route)),
150
+ );
151
+ const keptDefaults = defaultBlock.filter(
152
+ (entry) => !suppressed.has(entry.route) && !repositioned.has(entry.route),
153
+ );
154
+ const customBlock = visible.map((raw) => this.#customEntry(raw));
155
+ const hiddenBlock = hiddenRoutes.map((route) => new MenuEntry({ route, hidden: true }));
156
+
157
+ return [...this.#dedupe([...keptDefaults, ...customBlock]), ...hiddenBlock];
158
+ }
159
+
160
+ /**
161
+ * Validates each raw entry, dropping and warning on invalid ones. The
162
+ * `entries`-array index is kept for the warning wording.
163
+ * @param {Array<*>} rawEntries - The raw `entries` list.
164
+ * @returns {Array<{ entry: object, index: number }>} The valid raw entries.
165
+ */
166
+ static #collectValid(rawEntries) {
167
+ return rawEntries.reduce((valid, rawEntry, index) => {
168
+ const { valid: ok, reason } = MenuEntry.validate(rawEntry);
169
+
170
+ if (!ok) {
171
+ Logger.warn(`[menu] skipping invalid entry at index ${index}: ${reason}`);
172
+ return valid;
173
+ }
174
+
175
+ valid.push({ entry: rawEntry, index });
176
+ return valid;
177
+ }, []);
178
+ }
179
+
180
+ /**
181
+ * Partitions the valid raw entries into suppressed default routes, the visible
182
+ * entries, and the hidden non-default routes surfaced through `/menu.json`.
183
+ * @param {Array<{ entry: object, index: number }>} valid - The valid raw entries.
184
+ * @returns {{ suppressed: Set<string>, visible: Array<object>, hiddenRoutes: Array<string> }}
185
+ * The partition. `hiddenRoutes` is in file order and de-duplicated.
186
+ */
187
+ static #partitionHidden(valid) {
188
+ const suppressed = new Set();
189
+ const hidden = new Set();
190
+
191
+ const visible = valid.reduce((list, { entry }) => {
192
+ if (entry.hidden !== true) {
193
+ list.push(entry);
194
+ return list;
195
+ }
196
+
197
+ if (this.DEFAULT_ROUTES.includes(entry.route)) {
198
+ suppressed.add(entry.route);
199
+ return list;
200
+ }
201
+
202
+ hidden.add(entry.route);
203
+ return list;
204
+ }, []);
205
+
206
+ return { suppressed, visible, hiddenRoutes: [...hidden] };
207
+ }
208
+
209
+ /**
210
+ * Builds a {@link MenuEntry} from a visible raw entry, restoring the shipped
211
+ * label when a re-listed default omits its `text`.
212
+ * @param {object} raw - The visible raw entry.
213
+ * @returns {MenuEntry} The built entry.
214
+ */
215
+ static #customEntry(raw) {
216
+ if (!this.DEFAULT_ROUTES.includes(raw.route) || 'text' in raw) {
217
+ return MenuEntry.fromObject(raw);
218
+ }
219
+
220
+ return MenuEntry.fromObject(raw, this.defaultLabel(raw.route));
221
+ }
222
+
223
+ /**
224
+ * First-wins de-dup over the merged render-order list. Indices in the warning
225
+ * count positions in that merged list, not the raw file.
226
+ * @param {Array<MenuEntry>} merged - The merged render-order list.
227
+ * @returns {Array<MenuEntry>} The survivors, in order.
228
+ */
229
+ static #dedupe(merged) {
230
+ const firstIndex = new Map();
231
+
232
+ return merged.reduce((kept, entry, index) => {
233
+ if (firstIndex.has(entry.route)) {
234
+ Logger.warn(
235
+ `[menu] skipping duplicate entry at index ${index}: `
236
+ + `route "${entry.route}" already defined at index ${firstIndex.get(entry.route)}`,
237
+ );
238
+ return kept;
239
+ }
240
+
241
+ firstIndex.set(entry.route, index);
242
+ kept.push(entry);
243
+ return kept;
244
+ }, []);
245
+ }
246
+ }
247
+
248
+ export { MenuConfig };
@@ -0,0 +1,127 @@
1
+ const ALLOWED_KEYS = ['route', 'text', 'hidden'];
2
+ const URL_PATTERN = /^https?:\/\//;
3
+ const WHITESPACE_PATTERN = /\s/;
4
+
5
+ /**
6
+ * Represents a single internal navigation menu entry configured for the UI.
7
+ * @author darthjee
8
+ */
9
+ class MenuEntry {
10
+ /**
11
+ * Creates a MenuEntry instance.
12
+ * @param {object} params - Constructor params.
13
+ * @param {string} params.route - The entry route (internal SPA path or external URL).
14
+ * @param {string} [params.text] - Display text; defaults to the route.
15
+ * @param {boolean} [params.hidden=false] - Whether this entry is a hidden,
16
+ * non-default route surfaced only in `/menu.json`'s `hidden` list.
17
+ */
18
+ constructor({ route, text, hidden = false }) {
19
+ this.route = route;
20
+ this.text = text ?? route;
21
+ this.hidden = hidden === true;
22
+ }
23
+
24
+ /**
25
+ * Creates a MenuEntry instance from a YAML mapping entry.
26
+ *
27
+ * `MenuConfig` owns the reposition / label logic and may pass an already
28
+ * resolved `text` (e.g. a shipped default label) that wins over `entry.text`.
29
+ * `hidden` is intentionally not carried onto the instance — its meaning is
30
+ * applied in `MenuConfig`.
31
+ * @param {object} entry - A mapping with `route`, optional `text`, optional `hidden`.
32
+ * @param {string} [resolvedText] - A resolved display text that wins over `entry.text`.
33
+ * @returns {MenuEntry} The parsed MenuEntry instance.
34
+ */
35
+ static fromObject(entry, resolvedText) {
36
+ return new MenuEntry({ route: entry.route, text: resolvedText ?? entry.text });
37
+ }
38
+
39
+ /**
40
+ * Validates a raw menu entry mapping.
41
+ * @param {*} entry - The raw entry to validate.
42
+ * @returns {{ valid: boolean, reason: (string|undefined) }} Validation outcome.
43
+ */
44
+ static validate(entry) {
45
+ const reason = this.#firstReason(entry);
46
+
47
+ return reason ? { valid: false, reason } : { valid: true, reason: undefined };
48
+ }
49
+
50
+ /**
51
+ * Convenience boolean wrapper around {@link MenuEntry.validate}.
52
+ * @param {*} entry - The raw entry to validate.
53
+ * @returns {boolean} Whether the entry is valid.
54
+ */
55
+ static isValid(entry) {
56
+ return this.validate(entry).valid;
57
+ }
58
+
59
+ /**
60
+ * Serializes this entry for JSON responses. `hidden` is never serialized.
61
+ * @returns {{ route: string, text: string }} The serialized entry.
62
+ */
63
+ toJSON() {
64
+ return { route: this.route, text: this.text };
65
+ }
66
+
67
+ /**
68
+ * Returns the first validation failure reason for a raw entry, or undefined
69
+ * when the entry is valid.
70
+ * @param {*} entry - The raw entry to validate.
71
+ * @returns {(string|undefined)} The first failure reason, or undefined.
72
+ */
73
+ static #firstReason(entry) {
74
+ if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
75
+ return 'entry must be a mapping';
76
+ }
77
+
78
+ const unknownKey = Object.keys(entry).find((key) => !ALLOWED_KEYS.includes(key));
79
+ if (unknownKey) return `unknown key "${unknownKey}"`;
80
+
81
+ return this.#validateRoute(entry.route)
82
+ ?? this.#validateText(entry)
83
+ ?? this.#validateHidden(entry);
84
+ }
85
+
86
+ /**
87
+ * Validates the optional `text` field of a raw entry.
88
+ * @param {object} entry - The raw entry.
89
+ * @returns {(string|undefined)} A reason string when invalid, otherwise undefined.
90
+ */
91
+ static #validateText(entry) {
92
+ if (!('text' in entry)) return undefined;
93
+ if (typeof entry.text !== 'string' || entry.text.length === 0) {
94
+ return 'text must be a non-empty string';
95
+ }
96
+ return undefined;
97
+ }
98
+
99
+ /**
100
+ * Validates the optional `hidden` field of a raw entry.
101
+ * @param {object} entry - The raw entry.
102
+ * @returns {(string|undefined)} A reason string when invalid, otherwise undefined.
103
+ */
104
+ static #validateHidden(entry) {
105
+ if (!('hidden' in entry)) return undefined;
106
+ if (typeof entry.hidden !== 'boolean') return 'hidden must be a boolean';
107
+ return undefined;
108
+ }
109
+
110
+ /**
111
+ * Validates the `route` field of a raw entry.
112
+ * @param {*} route - The route value.
113
+ * @returns {(string|undefined)} A reason string when invalid, otherwise undefined.
114
+ */
115
+ static #validateRoute(route) {
116
+ if (typeof route !== 'string' || route.length === 0) {
117
+ return 'route is required and must be a non-empty string';
118
+ }
119
+ if (WHITESPACE_PATTERN.test(route)) return 'route must not contain whitespace';
120
+ if (!route.startsWith('/') && !URL_PATTERN.test(route)) {
121
+ return 'route must start with "/" or match ^https?://';
122
+ }
123
+ return undefined;
124
+ }
125
+ }
126
+
127
+ export { MenuEntry };
@@ -1,4 +1,4 @@
1
- import { ResourceRequest } from './ResourceRequest.js';
1
+ import { ResourceRequest } from './resource_request/ResourceRequest.js';
2
2
 
3
3
  /**
4
4
  * Resource class represents a resource with a name and associated resource requests.
@@ -1,4 +1,4 @@
1
- import { TokenResolver } from './TokenResolver.js';
1
+ import { TokenResolver } from '../tokens/TokenResolver.js';
2
2
 
3
3
  /**
4
4
  * TemplateStringRenderer renders a single template string against an item, resolving
@@ -1,15 +1,15 @@
1
1
  import { JobRegistry as DefaultJobRegistry } from 'deku-swarm';
2
- import { AssetRequest } from './AssetRequest.js';
3
- import { ClientReference } from './ClientReference.js';
2
+ import { AssetRequest } from '../AssetRequest.js';
3
+ import { ClientReference } from '../ClientReference.js';
4
4
  import { ResourceRequestAction } from './ResourceRequestAction.js';
5
5
  import { ResourceRequestEmit } from './ResourceRequestEmit.js';
6
6
  import { ResourceRequestPaginatedAction } from './ResourceRequestPaginatedAction.js';
7
7
  import { ResourceRequestParser } from './ResourceRequestParser.js';
8
- import { UrlTokenResolver } from './UrlTokenResolver.js';
9
- import { ActionsEnqueuer } from '../../enqueuers/ActionsEnqueuer.js';
10
- import { PaginatedActionsEnqueuer } from '../../enqueuers/PaginatedActionsEnqueuer.js';
11
- import { LogRegistry } from '../../registry/LogRegistry.js';
12
- import { Application } from '../../services/application/Application.js';
8
+ import { ActionsEnqueuer } from '../../../enqueuers/ActionsEnqueuer.js';
9
+ import { PaginatedActionsEnqueuer } from '../../../enqueuers/PaginatedActionsEnqueuer.js';
10
+ import { LogRegistry } from '../../../registry/LogRegistry.js';
11
+ import { Application } from '../../../services/application/Application.js';
12
+ import { UrlTokenResolver } from '../tokens/UrlTokenResolver.js';
13
13
 
14
14
  /**
15
15
  * ResourceRequest represents a request to a specific URL with an expected status code.
@@ -1,9 +1,9 @@
1
1
  import { JobRegistry as DefaultJobRegistry } from 'deku-swarm';
2
- import { MissingActionResource } from '../../exceptions/registry/MissingActionResource.js';
3
- import { LogRegistry } from '../../registry/LogRegistry.js';
4
- import { NamespaceMap as DefaultNamespaceMap } from '../../registry/NamespaceMap.js';
5
- import { Application } from '../../services/application/Application.js';
6
- import { ParametersMapper } from '../response/ParametersMapper.js';
2
+ import { MissingActionResource } from '../../../exceptions/registry/MissingActionResource.js';
3
+ import { LogRegistry } from '../../../registry/LogRegistry.js';
4
+ import { NamespaceMap as DefaultNamespaceMap } from '../../../registry/namespace/NamespaceMap.js';
5
+ import { Application } from '../../../services/application/Application.js';
6
+ import { ParametersMapper } from '../../response/ParametersMapper.js';
7
7
 
8
8
  /**
9
9
  * Represents a single action to execute after a successful resource request response.
@@ -1,12 +1,12 @@
1
- import { BodyTemplateRenderer } from './BodyTemplateRenderer.js';
2
- import { ClientReference } from './ClientReference.js';
3
- import { UrlTokenResolver } from './UrlTokenResolver.js';
4
- import { InvalidEmitBodyTemplate } from '../../exceptions/config/InvalidEmitBodyTemplate.js';
5
- import { InvalidEmitCooldown } from '../../exceptions/config/InvalidEmitCooldown.js';
6
- import { InvalidEmitHeaders } from '../../exceptions/config/InvalidEmitHeaders.js';
7
- import { InvalidEmitMethod } from '../../exceptions/config/InvalidEmitMethod.js';
8
- import { InvalidEmitRetries } from '../../exceptions/config/InvalidEmitRetries.js';
9
- import { MissingEmitUrl } from '../../exceptions/config/MissingEmitUrl.js';
1
+ import { InvalidEmitBodyTemplate } from '../../../exceptions/config/emit/InvalidEmitBodyTemplate.js';
2
+ import { InvalidEmitCooldown } from '../../../exceptions/config/emit/InvalidEmitCooldown.js';
3
+ import { InvalidEmitHeaders } from '../../../exceptions/config/emit/InvalidEmitHeaders.js';
4
+ import { InvalidEmitMethod } from '../../../exceptions/config/emit/InvalidEmitMethod.js';
5
+ import { InvalidEmitRetries } from '../../../exceptions/config/emit/InvalidEmitRetries.js';
6
+ import { MissingEmitUrl } from '../../../exceptions/config/emit/MissingEmitUrl.js';
7
+ import { ClientReference } from '../ClientReference.js';
8
+ import { BodyTemplateRenderer } from '../renderers/BodyTemplateRenderer.js';
9
+ import { UrlTokenResolver } from '../tokens/UrlTokenResolver.js';
10
10
 
11
11
  /**
12
12
  * The value types accepted for an individual `emit.headers` entry.
@@ -1,11 +1,11 @@
1
1
  import { JobRegistry as DefaultJobRegistry } from 'deku-swarm';
2
- import { MissingActionResource } from '../../exceptions/registry/MissingActionResource.js';
3
- import { LogRegistry } from '../../registry/LogRegistry.js';
4
- import { NamespaceMap as DefaultNamespaceMap } from '../../registry/NamespaceMap.js';
5
- import { Application } from '../../services/application/Application.js';
6
- import { PageRange } from '../configs/PageRange.js';
7
- import { PaginationConfig } from '../configs/PaginationConfig.js';
8
- import { ParametersMapper } from '../response/ParametersMapper.js';
2
+ import { MissingActionResource } from '../../../exceptions/registry/MissingActionResource.js';
3
+ import { LogRegistry } from '../../../registry/LogRegistry.js';
4
+ import { NamespaceMap as DefaultNamespaceMap } from '../../../registry/namespace/NamespaceMap.js';
5
+ import { Application } from '../../../services/application/Application.js';
6
+ import { PageRange } from '../../configs/PageRange.js';
7
+ import { PaginationConfig } from '../../configs/PaginationConfig.js';
8
+ import { ParametersMapper } from '../../response/ParametersMapper.js';
9
9
 
10
10
  /**
11
11
  * Represents a single paginated action to execute after a successful resource request response.
@@ -1,4 +1,4 @@
1
- import { InvalidParserType } from '../../exceptions/config/InvalidParserType.js';
1
+ import { InvalidParserType } from '../../../exceptions/config/parser/InvalidParserType.js';
2
2
 
3
3
  /**
4
4
  * The set of supported `parser.type` values.
@@ -2,8 +2,8 @@ import { FieldsMapper } from './css_selector_parser/FieldsMapper.js';
2
2
  import { FilterMatcher } from './css_selector_parser/FilterMatcher.js';
3
3
  import { ValueResolver } from './css_selector_parser/ValueResolver.js';
4
4
  import { HtmlRootParser } from '../common/utils/parser/HtmlRootParser.js';
5
- import { MissingParserField } from '../exceptions/config/MissingParserField.js';
6
- import { MissingParserMatch } from '../exceptions/config/MissingParserMatch.js';
5
+ import { MissingParserField } from '../exceptions/config/parser/MissingParserField.js';
6
+ import { MissingParserMatch } from '../exceptions/config/parser/MissingParserMatch.js';
7
7
 
8
8
  /**
9
9
  * CssSelectorParser extracts a list of mapped items from a raw HTML response body,
@@ -1,8 +1,7 @@
1
1
  import { FieldMapper } from './json_path/FieldMapper.js';
2
2
  import { FilterMatcher } from './json_path/FilterMatcher.js';
3
3
  import { MatchResolver } from './json_path/MatchResolver.js';
4
- import { MissingParserFields } from '../exceptions/config/MissingParserFields.js';
5
- import { MissingParserMatch } from '../exceptions/config/MissingParserMatch.js';
4
+ import { MissingParserFields } from '../exceptions/config/parser/MissingParserFields.js';
6
5
 
7
6
  /**
8
7
  * @typedef {object} ExtractedItem
@@ -28,8 +27,9 @@ class JsonPathParser {
28
27
  * and remapping fields via `attributes.fields`.
29
28
  * @param {string} rawBody The raw response body to extract data from (parsed as JSON).
30
29
  * @param {object} attributes The parser attributes.
31
- * @param {string} attributes.match The dot-notation path (e.g. `data.items`) to the array
32
- * to extract items from, resolved against the parsed body.
30
+ * @param {string} [attributes.match] The dot-notation path (e.g. `data.items`) to the array
31
+ * to extract items from, resolved against the parsed body. When absent, an empty string, or
32
+ * exactly `'.'`, the parsed body itself is treated as the array of items (root-array form).
33
33
  * @param {Array<object>} [attributes.filter] Optional list of AND'ed conditions an item
34
34
  * must satisfy to be included. Each condition is either `{ field, equals }` (literal
35
35
  * comparison) or `{ field, equals_field }` (field-to-field comparison, both fields read
@@ -39,13 +39,11 @@ class JsonPathParser {
39
39
  * @returns {Array<ExtractedItem>} An array of `{ [outputKey]: value, ... }` items, one per
40
40
  * matched item that passes `filter` (or all matched items when `filter` is absent). An empty
41
41
  * array when no items match or none pass the filter.
42
- * @throws {MissingParserMatch} If `attributes.match` is absent.
43
42
  * @throws {MissingParserFields} If `attributes.fields` is absent.
44
43
  * @throws {InvalidParserMatch} If `attributes.match` does not resolve to an array within
45
- * the parsed body.
44
+ * the parsed body, or the root-array form is used against a non-array body.
46
45
  */
47
46
  extract(rawBody, { match, filter, fields } = {}) {
48
- if (!match) throw new MissingParserMatch();
49
47
  if (!fields) throw new MissingParserFields();
50
48
 
51
49
  const parsedBody = JSON.parse(rawBody);
@@ -1,5 +1,5 @@
1
1
  import { ConditionMatcher } from './ConditionMatcher.js';
2
- import { Logger } from '../../utils/logging/Logger.js';
2
+ import { Logger } from '../../common/utils/logging/Logger.js';
3
3
 
4
4
  /**
5
5
  * FilterMatcher evaluates a list of AND'ed CSS parser conditions against a DOM
@@ -1,4 +1,4 @@
1
- import { InvalidParserMatch } from '../../exceptions/config/InvalidParserMatch.js';
1
+ import { InvalidParserMatch } from '../../exceptions/config/parser/InvalidParserMatch.js';
2
2
 
3
3
  /**
4
4
  * MatchResolver navigates a dot-notation `match` path against a parsed JSON
@@ -8,31 +8,49 @@ import { InvalidParserMatch } from '../../exceptions/config/InvalidParserMatch.j
8
8
  */
9
9
  class MatchResolver {
10
10
  /**
11
- * @param {string} match The dot-notation path (e.g. `data.items`) to the array
11
+ * @param {string} [match] The dot-notation path (e.g. `data.items`) to the array
12
12
  * to resolve, evaluated against the parsed body passed to {@link MatchResolver#resolve}.
13
+ * When absent, an empty string, or exactly `'.'`, the parsed body itself is treated
14
+ * as the array (root-array form).
13
15
  */
14
16
  constructor(match) {
15
17
  this.match = match;
16
18
  }
17
19
 
18
20
  /**
19
- * Resolves this resolver's `match` path against the given parsed body.
21
+ * Resolves this resolver's `match` path against the given parsed body. When
22
+ * `match` is absent, an empty string, or exactly `'.'`, the parsed body itself
23
+ * is returned as the array.
20
24
  * @param {object} parsedBody The parsed JSON body to navigate.
21
- * @returns {Array} The array resolved by navigating `match` against `parsedBody`.
25
+ * @returns {Array} The array resolved by navigating `match` against `parsedBody`,
26
+ * or `parsedBody` itself for the root-array form.
22
27
  * @throws {InvalidParserMatch} If `match` does not resolve to an array within
23
- * `parsedBody` (a missing intermediate key, or a resolved value that isn't an array).
28
+ * `parsedBody` (a missing intermediate key, or a resolved value that isn't an array),
29
+ * or the root-array form is used against a non-array body.
24
30
  */
25
31
  resolve(parsedBody) {
26
- const resolved = this.match.split('.').reduce((value, key) => {
27
- if (value === undefined || value === null) return undefined;
32
+ const resolved = this.#isRootMatch()
33
+ ? parsedBody
34
+ : this.match.split('.').reduce((value, key) => {
35
+ if (value === undefined || value === null) return undefined;
28
36
 
29
- return value[key];
30
- }, parsedBody);
37
+ return value[key];
38
+ }, parsedBody);
31
39
 
32
- if (!Array.isArray(resolved)) throw new InvalidParserMatch(this.match);
40
+ if (!Array.isArray(resolved)) {
41
+ throw new InvalidParserMatch(this.#isRootMatch() ? '.' : this.match);
42
+ }
33
43
 
34
44
  return resolved;
35
45
  }
46
+
47
+ /**
48
+ * @returns {boolean} `true` when `match` selects the parsed body itself (absent,
49
+ * empty string, or exactly `'.'`).
50
+ */
51
+ #isRootMatch() {
52
+ return !this.match || this.match === '.';
53
+ }
36
54
  }
37
55
 
38
56
  export { MatchResolver };
@@ -1,5 +1,5 @@
1
- import { MissingParserField } from '../../exceptions/config/MissingParserField.js';
2
- import { MissingParserMatch } from '../../exceptions/config/MissingParserMatch.js';
1
+ import { MissingParserField } from '../../exceptions/config/parser/MissingParserField.js';
2
+ import { MissingParserMatch } from '../../exceptions/config/parser/MissingParserMatch.js';
3
3
 
4
4
  /**
5
5
  * AttributesValidator validates the `match`/`field` attributes required by
@@ -1,4 +1,4 @@
1
- import { NamedRegistry } from './NamedRegistry.js';
1
+ import { NamedRegistry } from './namespace/NamedRegistry.js';
2
2
  import { ClientNotFound } from '../exceptions/registry/ClientNotFound.js';
3
3
 
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { EmissionRegistryInstance } from './EmissionRegistryInstance.js';
1
+ import { EmissionRegistryInstance } from './instances/EmissionRegistryInstance.js';
2
2
 
3
3
  /**
4
4
  * EmissionRegistry is a static singleton facade for the application's EmitJob emission
@@ -1,4 +1,4 @@
1
- import { ExtractionRegistryInstance } from './ExtractionRegistryInstance.js';
1
+ import { ExtractionRegistryInstance } from './instances/ExtractionRegistryInstance.js';
2
2
 
3
3
  /**
4
4
  * ExtractionRegistry is a static singleton facade for the application's ExtractionJob