navi-hey 1.4.0 → 1.5.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.
@@ -0,0 +1,167 @@
1
+ import { ConfigParser } from './ConfigParser.js';
2
+ import { DuplicateNamespaceItem } from '../exceptions/registry/DuplicateNamespaceItem.js';
3
+ import { Namespace } from '../registry/Namespace.js';
4
+ import { NamespaceMap } from '../registry/NamespaceMap.js';
5
+
6
+ /**
7
+ * NamespaceMapBuilder groups the per-file `{ namespace, resources, clients }` entries
8
+ * produced by `ConfigIncluder` into one `Namespace` per distinct namespace name, then
9
+ * eagerly validates every resource/client reference collected while parsing (actions,
10
+ * paginated_actions, and resource-level client references), so unresolvable
11
+ * references fail fast at load time rather than at request time.
12
+ * @author darthjee
13
+ */
14
+ class NamespaceMapBuilder {
15
+ #files;
16
+ #strict;
17
+
18
+ /**
19
+ * @param {Array<{namespace: string, resources: object, clients: object, filePath: string}>} files
20
+ * The flat list of files returned by `ConfigIncluder`.
21
+ */
22
+ constructor(files) {
23
+ this.#files = files;
24
+ this.#strict = files.length === 1;
25
+ }
26
+
27
+ /**
28
+ * Builds a namespace map from the given list of files.
29
+ * @param {Array<{namespace: string, resources: object, clients: object, filePath: string}>} files
30
+ * The flat list of files returned by `ConfigIncluder`.
31
+ * @returns {Record<string, Namespace>} A map of namespace name to Namespace instance.
32
+ */
33
+ static build(files) {
34
+ return new NamespaceMapBuilder(files).build();
35
+ }
36
+
37
+ /**
38
+ * Groups files by namespace, builds one Namespace per group, and eagerly
39
+ * validates every cross-reference before returning.
40
+ * @returns {Record<string, Namespace>} A map of namespace name to Namespace instance.
41
+ * @throws {DuplicateNamespaceItem} When two files sharing a namespace declare the
42
+ * same resource or client name.
43
+ * @throws {NamespaceNotFound|ResourceNotFound|ClientNotFound} When a resource/client
44
+ * reference cannot be resolved.
45
+ */
46
+ build() {
47
+ const namespaces = this.#buildNamespaces();
48
+ this.#validateReferences(namespaces);
49
+ return namespaces;
50
+ }
51
+
52
+ /**
53
+ * Groups every file's parsed resources/clients by namespace name, raising on
54
+ * duplicate names within a namespace group, then builds one Namespace per group.
55
+ * @returns {Record<string, Namespace>} A map of namespace name to Namespace instance.
56
+ * @private
57
+ */
58
+ #buildNamespaces() {
59
+ const groups = {};
60
+
61
+ this.#files.forEach((file) => {
62
+ const parsed = ConfigParser.fromObject(
63
+ this.#fileConfig(file),
64
+ { namespace: file.namespace, strict: this.#strict },
65
+ );
66
+
67
+ const group = groups[file.namespace] ??= { resources: {}, clients: {} };
68
+ this.#mergeInto(group.resources, parsed.resources, file.namespace, 'resource');
69
+ this.#mergeInto(group.clients, parsed.clients, file.namespace, 'client');
70
+ });
71
+
72
+ return Object.fromEntries(
73
+ Object.entries(groups).map(([name, { resources, clients }]) => {
74
+ return [name, new Namespace({ name, resources, clients })];
75
+ })
76
+ );
77
+ }
78
+
79
+ /**
80
+ * Builds the plain config object handed to `ConfigParser`, omitting the
81
+ * `resources`/`clients` keys entirely when the file did not declare them
82
+ * (as opposed to declaring them empty), so strict-mode key validation
83
+ * behaves correctly.
84
+ * @param {{resources: object|undefined, clients: object|undefined}} file A file entry from `ConfigIncluder`.
85
+ * @returns {object} A plain object with only the keys the file actually declared.
86
+ * @private
87
+ */
88
+ #fileConfig(file) {
89
+ const config = {};
90
+ if (file.resources !== undefined) config.resources = file.resources;
91
+ if (file.clients !== undefined) config.clients = file.clients;
92
+ return config;
93
+ }
94
+
95
+ /**
96
+ * Merges a file's parsed items into the namespace group's accumulator, raising
97
+ * when an item name is already present.
98
+ * @param {object} target The namespace group's accumulator map.
99
+ * @param {object} source The current file's parsed items.
100
+ * @param {string} namespace The namespace name being merged into.
101
+ * @param {string} itemType Either 'resource' or 'client' (used for the error message).
102
+ * @returns {void}
103
+ * @throws {DuplicateNamespaceItem} When an item name is already present in the group.
104
+ * @private
105
+ */
106
+ #mergeInto(target, source, namespace, itemType) {
107
+ Object.entries(source).forEach(([name, item]) => {
108
+ if (name in target) {
109
+ throw new DuplicateNamespaceItem(name, { namespace, itemType });
110
+ }
111
+ target[name] = item;
112
+ });
113
+ }
114
+
115
+ /**
116
+ * Walks every resource in every namespace and validates that its declared client
117
+ * reference, action targets, and paginated_action targets all resolve via the
118
+ * namespace map, raising immediately on the first unresolvable reference.
119
+ * @param {Record<string, Namespace>} namespaces A map of namespace name to Namespace instance.
120
+ * @returns {void}
121
+ * @private
122
+ */
123
+ #validateReferences(namespaces) {
124
+ const namespaceMap = new NamespaceMap(namespaces);
125
+
126
+ Object.values(namespaces).forEach((namespace) => {
127
+ namespace.resourceRegistry.filter(() => true).forEach((resource) => {
128
+ resource.resourceRequests.forEach((resourceRequest) => {
129
+ this.#validateClient(resourceRequest, namespaceMap);
130
+ this.#validateActions(resourceRequest, namespaceMap);
131
+ });
132
+ });
133
+ });
134
+ }
135
+
136
+ /**
137
+ * Validates a ResourceRequest's declared client reference, when present.
138
+ * @param {ResourceRequest} resourceRequest The resource request to validate.
139
+ * @param {NamespaceMap} namespaceMap The namespace map used to resolve the reference.
140
+ * @returns {void}
141
+ * @private
142
+ */
143
+ #validateClient(resourceRequest, namespaceMap) {
144
+ if (!resourceRequest.clientName) return;
145
+
146
+ namespaceMap.getClient(resourceRequest.namespace, resourceRequest.clientName, resourceRequest.clientNamespace);
147
+ }
148
+
149
+ /**
150
+ * Validates every action/paginated_action target resource declared on a ResourceRequest.
151
+ * @param {ResourceRequest} resourceRequest The resource request to validate.
152
+ * @param {NamespaceMap} namespaceMap The namespace map used to resolve references.
153
+ * @returns {void}
154
+ * @private
155
+ */
156
+ #validateActions(resourceRequest, namespaceMap) {
157
+ resourceRequest.actions.forEach((action) => {
158
+ namespaceMap.getResource(action.originNamespace, action.resource, action.namespace);
159
+ });
160
+
161
+ resourceRequest.paginatedActions.forEach((paginatedAction) => {
162
+ namespaceMap.getResource(paginatedAction.originNamespace, paginatedAction.resource, paginatedAction.namespace);
163
+ });
164
+ }
165
+ }
166
+
167
+ export { NamespaceMapBuilder };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "navi-hey",
3
3
  "type": "module",
4
- "version": "1.4.0",
4
+ "version": "1.5.0",
5
5
  "description": "Navi cache warmer CLI",
6
6
  "readme": "README.md",
7
7
  "main": "index.js",