@tech4good/platform-tooling 0.1.0-alpha.0 → 0.1.0-alpha.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.
- package/README.md +49 -16
- package/dist/firestore-indexes.d.ts +4 -0
- package/dist/firestore-indexes.js +33 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ checks local Firestore composite-index definitions against supported lab query
|
|
|
5
5
|
calls. It runs as compiled JavaScript on Node.js 22 or later and has no Angular
|
|
6
6
|
runtime or Firebase credential dependency.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The packaging pilot is currently versioned as `0.1.0-alpha.1`. The query analyzer was
|
|
9
9
|
extracted from angular-schematics without changing its index-planning behavior.
|
|
10
10
|
Store-feature discovery also recognizes named and aliased imports from packages
|
|
11
11
|
whose implementations are outside the scanned app sources.
|
|
@@ -14,10 +14,10 @@ This also improves discovery of stores created through an imported Angular
|
|
|
14
14
|
|
|
15
15
|
## Use in an application
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Install it as a development dependency:
|
|
18
18
|
|
|
19
19
|
```bash
|
|
20
|
-
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.
|
|
20
|
+
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.1
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
Use these package scripts (also emitted by the updated `ng-add` schematic):
|
|
@@ -57,6 +57,33 @@ local customizations and updating direct imports/callers. Do not rerun the
|
|
|
57
57
|
overwrite-based `ng-add` schematic to adopt this package. Future checker fixes
|
|
58
58
|
arrive by updating this dependency and its lockfile.
|
|
59
59
|
|
|
60
|
+
## Understand missing-index messages
|
|
61
|
+
|
|
62
|
+
Each missing index identifies the query that needs it. For example, a store
|
|
63
|
+
load with `problemCount > 3` and empty query options can report:
|
|
64
|
+
|
|
65
|
+
```text
|
|
66
|
+
Missing index: collections at src/app/main/home/home.component.ts:54 (initial load)
|
|
67
|
+
[{"fieldPath":"_deleted","order":"ASCENDING"},{"fieldPath":"problemCount","order":"ASCENDING"},{"fieldPath":"__name__","order":"ASCENDING"}]
|
|
68
|
+
Missing index: collections at src/app/main/home/home.component.ts:54 (incremental reload)
|
|
69
|
+
[{"fieldPath":"_deleted","order":"ASCENDING"},{"fieldPath":"_updatedAt","order":"ASCENDING"},{"fieldPath":"problemCount","order":"ASCENDING"},{"fieldPath":"__name__","order":"ASCENDING"}]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
An initial load uses your filters plus the store's `_deleted` filter. With empty
|
|
73
|
+
query options, later loads also add `_updatedAt > lastLoadTime` to fetch changes.
|
|
74
|
+
Those queries can need different indexes. Equality-only initial loads may be
|
|
75
|
+
covered by automatic indexes, so only the incremental index may be reported.
|
|
76
|
+
|
|
77
|
+
Other labels distinguish streams (initial results and live updates), counts,
|
|
78
|
+
aggregates, and direct database queries. A **full load with query options**
|
|
79
|
+
reuses the full query on subsequent loads, without an automatic timestamp cutoff.
|
|
80
|
+
When multiple calls or load stages need the same index, **Also needed for** lists
|
|
81
|
+
their purposes and locations. The definition is reported and added only once.
|
|
82
|
+
|
|
83
|
+
These message improvements are included in `0.1.0-alpha.1`; applications pinned to
|
|
84
|
+
`0.1.0-alpha.0` still use the earlier output. Use the local-development commands
|
|
85
|
+
below to try them before publishing.
|
|
86
|
+
|
|
60
87
|
## Programmatic API
|
|
61
88
|
|
|
62
89
|
Both ESM imports and CommonJS `require` are supported. Importing the library
|
|
@@ -79,6 +106,11 @@ that were found and added during that run; rerun without `fix` to verify the
|
|
|
79
106
|
resulting file. The package owns its TypeScript parser dependency, independently
|
|
80
107
|
of the application's compiler version.
|
|
81
108
|
|
|
109
|
+
Each missing index includes `query` for its first use and `queries` for all uses.
|
|
110
|
+
Each query's `purpose` is `initial-load`, `incremental-load`, `full-load`, `stream`,
|
|
111
|
+
`count`, `aggregate`, or `database-query`. Shared requirements remain one entry
|
|
112
|
+
in `missingIndexes`, even when multiple query purposes or locations need them.
|
|
113
|
+
|
|
82
114
|
## Supported scope
|
|
83
115
|
|
|
84
116
|
- Lab store `load`, `stream`, `count`, and `aggregate` calls.
|
|
@@ -131,7 +163,7 @@ npm run test:indexes
|
|
|
131
163
|
npm run pack:tooling
|
|
132
164
|
```
|
|
133
165
|
|
|
134
|
-
The last command creates `tech4good-platform-tooling-0.1.0-alpha.
|
|
166
|
+
The last command creates `tech4good-platform-tooling-0.1.0-alpha.1.tgz` in the repository
|
|
135
167
|
root. In a disposable application checkout, install its absolute path as a dev
|
|
136
168
|
dependency and apply the scripts shown above. A tarball installation exercises
|
|
137
169
|
the same compiled files, exports, and executable that npm consumers receive.
|
|
@@ -168,7 +200,7 @@ cd /path/to/angular-schematics
|
|
|
168
200
|
npm run pack:tooling
|
|
169
201
|
|
|
170
202
|
cd /path/to/math-pets
|
|
171
|
-
npm install --no-save --package-lock=false /path/to/angular-schematics/tech4good-platform-tooling-0.1.0-alpha.
|
|
203
|
+
npm install --no-save --package-lock=false /path/to/angular-schematics/tech4good-platform-tooling-0.1.0-alpha.1.tgz
|
|
172
204
|
./node_modules/.bin/t4g-check-firestore-indexes
|
|
173
205
|
```
|
|
174
206
|
|
|
@@ -214,14 +246,15 @@ the Angular/schematics version.
|
|
|
214
246
|
|
|
215
247
|
### 1. Prepare the version
|
|
216
248
|
|
|
217
|
-
|
|
218
|
-
|
|
249
|
+
This checkout is prepared for `0.1.0-alpha.1`. It is already set in the package
|
|
250
|
+
manifest, root lockfile, and generated dependency; do not bump again to publish
|
|
251
|
+
this release.
|
|
219
252
|
|
|
220
253
|
For a subsequent release, choose an unused version and bump only this workspace.
|
|
221
|
-
For example, after publishing `0.1.0-alpha.
|
|
254
|
+
For example, after publishing `0.1.0-alpha.1`, prepare the next alpha with:
|
|
222
255
|
|
|
223
256
|
```bash
|
|
224
|
-
npm version 0.1.0-alpha.
|
|
257
|
+
npm version 0.1.0-alpha.2 --workspace @tech4good/platform-tooling --no-git-tag-version --ignore-scripts
|
|
225
258
|
```
|
|
226
259
|
|
|
227
260
|
Replace the example version with the one being released. This updates
|
|
@@ -261,7 +294,7 @@ Publish from that reviewed release commit.
|
|
|
261
294
|
|
|
262
295
|
### 3. Publish to npm
|
|
263
296
|
|
|
264
|
-
For
|
|
297
|
+
For this alpha release:
|
|
265
298
|
|
|
266
299
|
```bash
|
|
267
300
|
npm login
|
|
@@ -289,20 +322,20 @@ different contents, so later changes require a new version.
|
|
|
289
322
|
|
|
290
323
|
### 4. Verify and record the published release
|
|
291
324
|
|
|
292
|
-
For
|
|
325
|
+
For this alpha (substitute the actual version for later releases):
|
|
293
326
|
|
|
294
327
|
```bash
|
|
295
|
-
npm view @tech4good/platform-tooling@0.1.0-alpha.
|
|
328
|
+
npm view @tech4good/platform-tooling@0.1.0-alpha.1 version
|
|
296
329
|
npm view @tech4good/platform-tooling dist-tags
|
|
297
|
-
git tag -a platform-tooling-v0.1.0-alpha.
|
|
330
|
+
git tag -a platform-tooling-v0.1.0-alpha.1 -m "Release @tech4good/platform-tooling 0.1.0-alpha.1"
|
|
298
331
|
```
|
|
299
332
|
|
|
300
|
-
Confirm the first command returns `0.1.0-alpha.
|
|
333
|
+
Confirm the first command returns `0.1.0-alpha.1` and the `alpha` tag points to
|
|
301
334
|
that version. Create the Git tag on the release commit, and push that commit
|
|
302
335
|
through the repository's normal Git workflow. Then push this specific tag:
|
|
303
336
|
|
|
304
337
|
```bash
|
|
305
|
-
git push origin platform-tooling-v0.1.0-alpha.
|
|
338
|
+
git push origin platform-tooling-v0.1.0-alpha.1
|
|
306
339
|
```
|
|
307
340
|
|
|
308
341
|
The `platform-tooling-v` prefix distinguishes tooling releases from the existing
|
|
@@ -314,7 +347,7 @@ npm before releasing angular-schematics with a template that references it.
|
|
|
314
347
|
From the application's directory, install the chosen published version:
|
|
315
348
|
|
|
316
349
|
```bash
|
|
317
|
-
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.
|
|
350
|
+
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.1
|
|
318
351
|
npm run check:indexes
|
|
319
352
|
```
|
|
320
353
|
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
type Direction = 'ASCENDING' | 'DESCENDING';
|
|
2
|
+
type QueryPurpose = 'initial-load' | 'incremental-load' | 'full-load' | 'stream' | 'count' | 'aggregate' | 'database-query';
|
|
2
3
|
interface FirestoreIndexField {
|
|
3
4
|
fieldPath: string;
|
|
4
5
|
order?: Direction;
|
|
@@ -24,6 +25,7 @@ interface Query {
|
|
|
24
25
|
filters: Filter[];
|
|
25
26
|
orderBy: Sort[];
|
|
26
27
|
aggregateFields: string[];
|
|
28
|
+
purpose: QueryPurpose;
|
|
27
29
|
}
|
|
28
30
|
interface Diagnostic {
|
|
29
31
|
file: string;
|
|
@@ -32,7 +34,9 @@ interface Diagnostic {
|
|
|
32
34
|
}
|
|
33
35
|
interface MissingIndex {
|
|
34
36
|
collection: string;
|
|
37
|
+
/** First use, retained for consumers of the original API. */
|
|
35
38
|
query: Query;
|
|
39
|
+
queries: Query[];
|
|
36
40
|
requiredFields: FirestoreIndexField[];
|
|
37
41
|
}
|
|
38
42
|
export interface CheckResult {
|
|
@@ -40,6 +40,15 @@ exports.checkFirestoreIndexes = checkFirestoreIndexes;
|
|
|
40
40
|
const fs = __importStar(require("node:fs"));
|
|
41
41
|
const path = __importStar(require("node:path"));
|
|
42
42
|
const typescript_1 = __importDefault(require("typescript"));
|
|
43
|
+
const purposeLabels = {
|
|
44
|
+
'initial-load': 'initial load',
|
|
45
|
+
'incremental-load': 'incremental reload',
|
|
46
|
+
'full-load': 'full load with query options',
|
|
47
|
+
stream: 'stream',
|
|
48
|
+
count: 'count',
|
|
49
|
+
aggregate: 'aggregate',
|
|
50
|
+
'database-query': 'direct database query',
|
|
51
|
+
};
|
|
43
52
|
const equalityOps = new Set(['==', 'in']);
|
|
44
53
|
const rangeOps = new Set(['<', '<=', '>', '>=', '!=', 'not-in']);
|
|
45
54
|
const arrayOps = new Set(['array-contains', 'array-contains-any']);
|
|
@@ -438,7 +447,10 @@ function extractQueries(files, root, literals, mappings) {
|
|
|
438
447
|
const filters = parseFilters(node.arguments[offset], literals);
|
|
439
448
|
const { orderBy, hasOptions } = parseOptions(node.arguments[offset + 1], literals);
|
|
440
449
|
const aggregateFields = method === 'aggregate' ? parseAggregates(node.arguments[offset + 2], literals) : [];
|
|
441
|
-
const
|
|
450
|
+
const purpose = operation === 'load' ? (hasOptions ? 'full-load' : 'initial-load') :
|
|
451
|
+
method === 'count' || method === 'aggregate' ? method :
|
|
452
|
+
operation === 'stream' || method === 'streamEntities' || method === 'streamEntitiesChanges' ? 'stream' : 'database-query';
|
|
453
|
+
const query = { file: relative, line, rawText: node.getText(file), collection: segments[segments.length - 1], filters, orderBy, aggregateFields, purpose };
|
|
442
454
|
if (new Set(filters.filter((filter) => arrayOps.has(filter.operator)).map((filter) => filter.field)).size > 1)
|
|
443
455
|
throw new Error('Queries with multiple array fields are unsupported by composite indexes.');
|
|
444
456
|
checked++;
|
|
@@ -453,7 +465,7 @@ function extractQueries(files, root, literals, mappings) {
|
|
|
453
465
|
const active = { ...query, filters: [...filters, { field: '_deleted', operator: '==' }] };
|
|
454
466
|
queries.push(active);
|
|
455
467
|
if (operation === 'load' && !hasOptions) {
|
|
456
|
-
queries.push({ ...active, filters: [...active.filters, { field: '_updatedAt', operator: '>' }] });
|
|
468
|
+
queries.push({ ...active, purpose: 'incremental-load', filters: [...active.filters, { field: '_updatedAt', operator: '>' }] });
|
|
457
469
|
}
|
|
458
470
|
}
|
|
459
471
|
}
|
|
@@ -618,7 +630,7 @@ function checkFirestoreIndexes(options = {}) {
|
|
|
618
630
|
const extracted = extractQueries(files, root, literals, discoverMappings(files, literals));
|
|
619
631
|
result.checkedQueries = extracted.checked;
|
|
620
632
|
result.unresolvedQueries.push(...extracted.diagnostics);
|
|
621
|
-
const signatures = new
|
|
633
|
+
const signatures = new Map();
|
|
622
634
|
for (const query of extracted.queries) {
|
|
623
635
|
const required = plan(query);
|
|
624
636
|
if (satisfied(query, required, indexes))
|
|
@@ -630,13 +642,27 @@ function checkFirestoreIndexes(options = {}) {
|
|
|
630
642
|
continue;
|
|
631
643
|
}
|
|
632
644
|
const signature = JSON.stringify([query.collection, required.fields]);
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
645
|
+
const existing = signatures.get(signature);
|
|
646
|
+
if (existing) {
|
|
647
|
+
existing.queries.push(query);
|
|
648
|
+
}
|
|
649
|
+
else {
|
|
650
|
+
const missing = { collection: query.collection, query, queries: [query], requiredFields: required.fields };
|
|
651
|
+
signatures.set(signature, missing);
|
|
652
|
+
result.missingIndexes.push(missing);
|
|
636
653
|
}
|
|
637
654
|
}
|
|
638
655
|
for (const missing of result.missingIndexes) {
|
|
639
|
-
|
|
656
|
+
const alsoNeeded = missing.queries.slice(1).map((query) => `\n Also needed for ${purposeLabels[query.purpose]} at ${query.file}:${query.line}`).join('');
|
|
657
|
+
log(`Missing index: ${missing.collection} at ${missing.query.file}:${missing.query.line} (${purposeLabels[missing.query.purpose]})${alsoNeeded}\n ${JSON.stringify(missing.requiredFields)}`);
|
|
658
|
+
}
|
|
659
|
+
const missingPurposes = new Set(result.missingIndexes.flatMap((missing) => missing.queries.map((query) => query.purpose)));
|
|
660
|
+
if (missingPurposes.has('initial-load') || missingPurposes.has('incremental-load')) {
|
|
661
|
+
log('Load behavior: initial loads use your filters plus _deleted. With empty query options, incremental reloads also add _updatedAt > lastLoadTime.');
|
|
662
|
+
log('These query shapes can need different indexes; equality-only initial loads may be covered by automatic indexes.');
|
|
663
|
+
}
|
|
664
|
+
if (missingPurposes.has('full-load')) {
|
|
665
|
+
log('Loads with non-empty query options reuse the full query on subsequent loads; no automatic _updatedAt cutoff is added.');
|
|
640
666
|
}
|
|
641
667
|
if (options.fix && result.missingIndexes.length) {
|
|
642
668
|
indexes.indexes.push(...result.missingIndexes.map((missing) => ({
|