Automatic Temporal Extent Calculation for Collections

[matthewhanson]

Adds automatic temporal extent calculation for STAC collections based on the
actual datetime range of items in the collection.

Changes

• Automatic calculation: Collections without a predefined temporal extent now have it calculated
dynamically from their items when served via the API
• Opt-in behavior: Only collections without extent.temporal.interval defined will have it auto-calculated
• Performant implementation: Uses efficient sorting queries (ascending/descending) rather than aggregations
• Empty collection handling: Collections with no items return [[null, null]]
• Endpoints affected: /collections and /collections/{collectionId}

Implementation

• Added getTemporalExtentFromItems() function in src/lib/database.js that uses two parallel sort queries to find earliest and latest item datetimes
• Added populateTemporalExtentIfMissing() helper in src/lib/api.js to check and populate temporal extent
• Updated both collection endpoints to call the helper function

Configuration

When ingesting collections, omit extent.temporal.interval to enable automatic calculation:

{
  "id": "my-collection",
  "extent": {
    "spatial": {...}
    // No temporal extent defined - will be calculated automatically
  }
}

Closes #1050

[Copilot]

Pull Request Overview

This PR adds automatic temporal extent calculation for STAC collections based on item datetime ranges. Collections without predefined temporal extents will have them calculated dynamically when served via the API, using efficient sort queries to find the earliest and latest item datetimes.

Key changes:

• Added getTemporalExtentFromItems() function that uses parallel ascending/descending sort queries to efficiently find temporal boundaries
• Collections without extent.temporal.interval now have it auto-calculated from their items
• Empty collections return [[null, null]] as their temporal extent

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/lib/database.js	Added getTemporalExtentFromItems() function to query earliest and latest item datetimes using parallel sort operations
src/lib/api.js	Added populateTemporalExtentIfMissing() helper and integrated it into collection endpoints
tests/system/test-api-temporal-extent.js	Added comprehensive test suite covering temporal extent calculation for collections with items and empty collections
README.md	Added documentation for the automatic temporal extent feature
CHANGELOG.md	Added entry documenting the new automatic temporal extent calculation feature

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This check is insufficient to determine if temporal extent is defined. A collection with extent.temporal.interval set to [[null, null]] will fail this check (both values are not undefined), but this should be treated as missing temporal extent since null values indicate no data. The check should verify that at least one of the values is non-null: collection.extent?.temporal?.interval?.[0]?.[0] || collection.extent?.temporal?.interval?.[0]?.[1]

Suggested change

	const hasTemporalExtent = collection.extent?.temporal?.interval?.[0]?.[0] !== undefined
	|| collection.extent?.temporal?.interval?.[0]?.[1] !== undefined
	const start = collection.extent?.temporal?.interval?.[0]?.[0];
	const end = collection.extent?.temporal?.interval?.[0]?.[1];
	const hasTemporalExtent = start != null || end != null;

[Copilot]

Pull Request Overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pjhartzell]

Looks reasonable to me.

[matthewhanson]

Synced to main + fixed the test failures

Rebased onto current main (merge) and ported this feature through the TypeScript migration that landed since this branch was opened. Three things were broken and are now fixed — this PR's tests had never passed in CI:

1. Ported to TS. src/lib/api.js and src/lib/database.js were converted to .ts on main. The new getTemporalExtentFromItems (now in database.ts) and populateTemporalExtentIfMissing (in api.ts) are reimplemented with proper types; getTemporalExtentFromItems added to the Backend interface in types.ts. Also switched the OpenSearch call to the dbQuery helper and _sourceIncludes (the typed equivalent of the old body._source).

2. Fixed the populate condition (behavior change — please confirm). The guard was start != null || end != null ("has extent if either bound is set"), so a collection with a partial/open extent like [["2013-06-01", null]] was treated as complete and never populated — which is why GET /collections/:id returns temporal extent from items failed. Changed to start != null && end != null, i.e. recompute from items whenever either bound is missing. This matches what the test asserts (it expects the interval to become the item min/max). Note this means a declared-but-open start (2013) is replaced by the earliest item datetime (2015) — that's the intent encoded in the test, flagging it so you can confirm.

3. Fixed a missing fixture. The test referenced tests/fixtures/stac/LC80100102015002LGN00.json, which was never committed (so the before-hook always ENOENT'd). Repointed it to the existing LC80100102015050LGN00.json — the test overrides id/datetime anyway.

Verified locally (clean env)

typecheck ✓ · lint ✓ · test:unit (69) ✓ · test:system (174, incl. the 3 temporal-extent tests) ✓ · build ✓

CI note

audit-prod will be red here until #1118 merges to main — this branch still carries the pre-#1118 .nsprc/lockfile, which is the same repo-wide audit-gate failure #1118 fixes. Recommend merging #1118 first, then this picks up the fix on the next sync.