@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 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
- This is an unpublished `0.1.0-alpha.0` packaging pilot. The query analyzer was
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
- Once this version is published, install it as a development dependency:
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.0
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.0.tgz` in the repository
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.0.tgz
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
- For the first pilot release, keep the existing `0.1.0-alpha.0` version. It is
218
- already set in the package manifest, root lockfile, and generated dependency.
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.0`, prepare the next alpha with:
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.1 --workspace @tech4good/platform-tooling --no-git-tag-version --ignore-scripts
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 the first alpha release:
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 the first alpha (substitute the actual version for later releases):
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.0 version
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.0 -m "Release @tech4good/platform-tooling 0.1.0-alpha.0"
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.0` and the `alpha` tag points to
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.0
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.0
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 query = { file: relative, line, rawText: node.getText(file), collection: segments[segments.length - 1], filters, orderBy, aggregateFields };
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 Set();
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
- if (!signatures.has(signature)) {
634
- signatures.add(signature);
635
- result.missingIndexes.push({ collection: query.collection, query, requiredFields: required.fields });
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
- log(`Missing index: ${missing.collection} at ${missing.query.file}:${missing.query.line}\n ${JSON.stringify(missing.requiredFields)}`);
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) => ({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tech4good/platform-tooling",
3
- "version": "0.1.0-alpha.0",
3
+ "version": "0.1.0-alpha.1",
4
4
  "description": "Development tools for Tech4Good Angular and Firebase applications.",
5
5
  "license": "MIT",
6
6
  "type": "commonjs",