@beesolve/analytics-processor 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -363,6 +363,18 @@ interface RollupModels {
 	readonly markers: Pick<AppliedMarkers, "isApplied" | "buildMarkerPut">;
 }
 type View = Grain | "year";
+/**
+* How a bucket's value was obtained, so the UI can tell "no traffic" apart from
+* "not calculated yet":
+* - `sealed`: a finalized, rolled-up period read from its stored aggregate. A
+*   zero-hit sealed bucket is genuine "no traffic".
+* - `partial`: an in-progress period computed live from the finer grain; the
+*   value is real but may still grow.
+* - `pending`: a period past its expected processing time with no stored data
+*   and nothing computable yet — awaiting processing.
+*/
+declare const bucketStates: readonly ["sealed", "partial", "pending"];
+type BucketState = (typeof bucketStates)[number];
 interface ResolveModels {
 	readonly totals: Pick<Totals, "queryWindow" | "getOne">;
 	readonly breakdowns: Pick<Breakdowns, "getForPeriod">;
@@ -370,15 +382,21 @@ interface ResolveModels {
 }
 /**
 * Resolves one bucket's totals, computing an in-progress period on the fly from
-* the grain below it. A past period whose rollup marker is applied is read
-* directly from the stored aggregate ("sealed"); the current period, and any
-* past period still missing its marker, is summed from its children — the
-* current month folds down through the current day to the hours ingested so far.
+* exactly one grain finer, following only the current edge deeper.
+*
+* A sealed period (strictly past, rollup marker applied) is read from its stored
+* aggregate. Otherwise the period is the sum of its children at the next finer
+* grain, where every already-complete child is taken from its stored aggregate
+* and only the single in-progress child is resolved recursively:
 *
-* Each level reads its children with a single ranged query (never a get per
-* child): a day sums its hours via one hourly `queryWindow`; a month sums its
-* days, and the one in-progress day among them is resolved from hours. `hour`
-* is terminal.
+* - partial day   = stored/queried hours `00..currentHour`
+* - partial month = stored days `01..currentDay-1` + the partial current day
+* - partial year  = stored months `01..currentMonth-1` + the partial current month
+*
+* So a partial month never fans out to hours for its finished days (it trusts
+* their day aggregate) — only the one current day drills into hours. Each level
+* is one ranged query, keeping the read count bounded (a year touches ~12
+* months + ~31 days + ~24 hours) and the request sub-second.
 */
 declare function resolveTotalsLive({ models, grain, periodKey, now }: {
 	readonly models: ResolveModels;
@@ -393,6 +411,20 @@ declare function resolveBreakdownLive({ models, dimension, grain, periodKey, now
 	readonly periodKey: string;
 	readonly now: Date;
 }): Promise<Array<BreakdownRow>>;
+/**
+* Classifies a bucket as sealed / partial / pending without recomputing its
+* value. A sealed bucket is a finalized rollup (its marker is applied), so a
+* zero-hit sealed bucket is genuine "no traffic". A non-sealed bucket that
+* yielded data is in-progress (`partial`); one with nothing to show is awaiting
+* processing (`pending`).
+*/
+declare function classifyBucketState({ models, grain, periodKey, now, hasData }: {
+	readonly models: ResolveModels;
+	readonly grain: Grain;
+	readonly periodKey: string;
+	readonly now: Date;
+	readonly hasData: boolean;
+}): Promise<BucketState>;
 declare function yearKey(date: Date): string;
 declare function monthKey2(date: Date): string;
 declare function dayKey2(date: Date): string;
@@ -423,4 +455,4 @@ declare function hoursBetween({ from, to }: {
 	from: Date;
 	to: Date;
 }): Array<string>;
-export { AnalyticsConfig, AppliedMarker, AppliedMarkers, AppliedSource, AthenaColumnMap, BreakdownInput, BreakdownItem, BreakdownRow, Breakdowns, Config, DeviceBucket, Dimension, Grain, HourlyAthenaResult, HourlyAthenaTotals, ProcessHourAthena, ProcessHourModels, ProcessHourOptions, ProcessHourResult, ResolveModels, SummedTotals, Totals, TotalsInput, TotalsItem, TransactItem, View, appliedMarkerSchema, appliedSources, applyDailyRollup, applyMonthlyRollup, breakdownSchema, buildHourlyQuery, chunkTransactItems, classifyDevice, columnMaps, configSchema, dayKey2 as dayKey, dimensions, grainForPeriodKey, grains, hourKey2 as hourKey, hourKeyParts, hoursBetween, maxWindowFor, monthKey2 as monthKey, parsePeriodKey, processHour, requiredRecordFields, resolveBreakdownLive, resolveTotalsLive, runHourlyAthenaQuery, shiftAnchor, sumBreakdown, sumTotals, topNWithOther, totalsSchema, windowKeys, yearKey };
+export { AnalyticsConfig, AppliedMarker, AppliedMarkers, AppliedSource, AthenaColumnMap, BreakdownInput, BreakdownItem, BreakdownRow, Breakdowns, BucketState, Config, DeviceBucket, Dimension, Grain, HourlyAthenaResult, HourlyAthenaTotals, ProcessHourAthena, ProcessHourModels, ProcessHourOptions, ProcessHourResult, ResolveModels, SummedTotals, Totals, TotalsInput, TotalsItem, TransactItem, View, appliedMarkerSchema, appliedSources, applyDailyRollup, applyMonthlyRollup, breakdownSchema, bucketStates, buildHourlyQuery, chunkTransactItems, classifyBucketState, classifyDevice, columnMaps, configSchema, dayKey2 as dayKey, dimensions, grainForPeriodKey, grains, hourKey2 as hourKey, hourKeyParts, hoursBetween, maxWindowFor, monthKey2 as monthKey, parsePeriodKey, processHour, requiredRecordFields, resolveBreakdownLive, resolveTotalsLive, runHourlyAthenaQuery, shiftAnchor, sumBreakdown, sumTotals, topNWithOther, totalsSchema, windowKeys, yearKey };

package/dist/index.js

@@ -837,6 +837,7 @@ function toBreakdownRow(item) {
   return { value: item.value, hits: item.hits, bytes: item.bytes };
 }
 // packages/analytics-processor/src/resolveLive.ts
+var bucketStates = ["sealed", "partial", "pending"];
 var emptyTotals = {
   hits: 0,
   success: 0,
@@ -870,21 +871,22 @@ async function resolveTotalsLive({
     });
     return sumTotals(hours);
   }
-  const dayKeys = dayKeysInProgress({ periodKey, now });
-  const sealedDays = await models.totals.queryWindow({
+  const storedDays = await models.totals.queryWindow({
     grain: "day",
     startKey: `${periodKey}-01`,
     endKey: `${periodKey}-31`
   });
-  const sealedByKey = indexByTimeKey(sealedDays);
-  const resolvedDays = await Promise.all(dayKeys.map(async (dayKey) => {
-    const stored = sealedByKey[dayKey];
-    if (stored != null && !isCurrentPeriod({ grain: "day", periodKey: dayKey, now })) {
-      return pickTotals(stored);
-    }
-    return resolveTotalsLive({ models, grain: "day", periodKey: dayKey, now });
-  }));
-  return sumTotals(resolvedDays);
+  const base = sumTotals(storedDays.filter((item) => !isCurrentPeriod({ grain: "day", periodKey: item.timeKey, now })));
+  const currentDayKey = currentChildKey({ parentGrain: "month", periodKey, now });
+  if (currentDayKey == null)
+    return base;
+  const currentDay = await resolveTotalsLive({
+    models,
+    grain: "day",
+    periodKey: currentDayKey,
+    now
+  });
+  return sumTotals([base, currentDay]);
 }
 async function resolveBreakdownLive({
   models,
@@ -901,10 +903,39 @@ async function resolveBreakdownLive({
     if (stored.length > 0)
       return toRows(stored);
   }
-  const finer = finerGrain(grain);
-  const childKeys = grain === "day" ? hourKeysInProgress({ periodKey, now }) : dayKeysInProgress({ periodKey, now });
-  const children = await Promise.all(childKeys.map((childKey) => resolveBreakdownLive({ models, dimension, grain: finer, periodKey: childKey, now })));
-  return sumBreakdown(children.flat());
+  if (grain === "day") {
+    const hourKeys = hourKeysInProgress({ periodKey, now });
+    const hourRows = await Promise.all(hourKeys.map((hourKey) => models.breakdowns.getForPeriod({ dimension, grain: "hour", periodKey: hourKey })));
+    return sumBreakdown(hourRows.flat().map(toRow));
+  }
+  const storedDayKeys = pastDayKeys({ periodKey, now });
+  const storedDayRows = await Promise.all(storedDayKeys.map((dayKey) => models.breakdowns.getForPeriod({ dimension, grain: "day", periodKey: dayKey })));
+  const rows = storedDayRows.flat().map(toRow);
+  const currentDayKey = currentChildKey({ parentGrain: "month", periodKey, now });
+  if (currentDayKey != null) {
+    const currentDay = await resolveBreakdownLive({
+      models,
+      dimension,
+      grain: "day",
+      periodKey: currentDayKey,
+      now
+    });
+    rows.push(...currentDay);
+  }
+  return sumBreakdown(rows);
+}
+async function classifyBucketState({
+  models,
+  grain,
+  periodKey,
+  now,
+  hasData
+}) {
+  if (await isSealed({ models, grain, periodKey, now }))
+    return "sealed";
+  if (hasData)
+    return "partial";
+  return "pending";
 }
 async function isSealed({
   models,
@@ -912,7 +943,7 @@ async function isSealed({
   periodKey,
   now
 }) {
-  if (isCurrentPeriod({ grain, periodKey, now }))
+  if (!isPastPeriod({ grain, periodKey, now }))
     return false;
   return models.markers.isApplied({ grain, periodKey });
 }
@@ -923,6 +954,13 @@ function isCurrentPeriod({
 }) {
   return periodKey === currentKeyFor({ grain, now });
 }
+function isPastPeriod({
+  grain,
+  periodKey,
+  now
+}) {
+  return periodKey < currentKeyFor({ grain, now });
+}
 function currentKeyFor({ grain, now }) {
   const year = pad4(now.getUTCFullYear());
   const month = pad2(now.getUTCMonth() + 1);
@@ -934,8 +972,14 @@ function currentKeyFor({ grain, now }) {
     return `${year}-${month}-${day}`;
   return `${year}-${month}-${day}-${hour}`;
 }
-function finerGrain(grain) {
-  return grain === "month" ? "day" : "hour";
+function currentChildKey({
+  parentGrain,
+  periodKey,
+  now
+}) {
+  if (!isCurrentPeriod({ grain: parentGrain, periodKey, now }))
+    return null;
+  return currentKeyFor({ grain: "day", now });
 }
 function hourKeysInProgress({
   periodKey,
@@ -948,11 +992,12 @@ function hourKeysInProgress({
   }
   return keys;
 }
-function dayKeysInProgress({
+function pastDayKeys({
   periodKey,
   now
 }) {
-  const lastDay = isCurrentPeriod({ grain: "month", periodKey, now }) ? now.getUTCDate() : daysInMonth(periodKey);
+  const isCurrentMonth = isCurrentPeriod({ grain: "month", periodKey, now });
+  const lastDay = isCurrentMonth ? now.getUTCDate() - 1 : daysInMonth(periodKey);
   const keys = [];
   for (let day = 1;day <= lastDay; day += 1) {
     keys.push(`${periodKey}-${pad2(day)}`);
@@ -963,15 +1008,11 @@ function daysInMonth(monthKey) {
   const [year, month] = monthKey.split("-").map(Number);
   return new Date(Date.UTC(year ?? 1970, month ?? 1, 0)).getUTCDate();
 }
-function indexByTimeKey(items) {
-  const byKey = {};
-  for (const item of items) {
-    byKey[item.timeKey] = item;
-  }
-  return byKey;
+function toRow(item) {
+  return { value: item.value, hits: item.hits, bytes: item.bytes };
 }
 function toRows(items) {
-  return items.map((item) => ({ value: item.value, hits: item.hits, bytes: item.bytes }));
+  return items.map(toRow);
 }
 function pickTotals(item) {
   return {
@@ -1223,8 +1264,10 @@ export {
   applyDailyRollup,
   applyMonthlyRollup,
   breakdownSchema,
+  bucketStates,
   buildHourlyQuery,
   chunkTransactItems,
+  classifyBucketState,
   classifyDevice,
   columnMaps,
   configSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beesolve/analytics-processor",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CloudFront analytics processor — Athena-to-DynamoDB hourly totals, breakdowns, and rollups",
   "homepage": "https://github.com/BeeSolve/packages/tree/main/packages/analytics-processor#readme",
   "license": "MIT",