s3db.js 11.0.3 → 11.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "11.0.3",
+  "version": "11.0.5",
   "description": "Use AWS S3, the world's most reliable document storage, as a database with this ORM.",
   "main": "dist/s3db.cjs.js",
   "module": "dist/s3db.es.js",

package/src/plugins/eventual-consistency/analytics.js

@@ -265,9 +265,9 @@ async function rollupPeriod(period, cohort, sourcePrefix, analyticsResource, con
   if (period === 'day') {
     sourcePeriod = 'hour';
   } else if (period === 'week') {
-    sourcePeriod = 'day';
+    sourcePeriod = 'day';  // Week aggregates from days
   } else if (period === 'month') {
-    sourcePeriod = 'week'; // Aggregate weeks to month
+    sourcePeriod = 'day';  // ✅ Month aggregates from days AND hours (like week)
   } else {
     sourcePeriod = 'day'; // Fallback
   }
@@ -291,6 +291,8 @@ async function rollupPeriod(period, cohort, sourcePrefix, analyticsResource, con
     });
   } else {
     // For day and month, simple prefix matching works
+    // day: aggregates from hours (cohort '2025-10-09' matches '2025-10-09T14', '2025-10-09T15', etc)
+    // month: aggregates from days (cohort '2025-10' matches '2025-10-01', '2025-10-02', etc)
     sourceAnalytics = allAnalytics.filter(a =>
       a.period === sourcePeriod && a.cohort.startsWith(sourcePrefix)
     );
@@ -806,3 +808,242 @@ export async function getTopRecords(resourceName, field, options, fieldHandlers)
   // Limit results
   return records.slice(0, limit);
 }
+
+/**
+ * Get analytics for entire year, broken down by days
+ *
+ * @param {string} resourceName - Resource name
+ * @param {string} field - Field name
+ * @param {number} year - Year (e.g., 2025)
+ * @param {Object} options - Options
+ * @param {Object} fieldHandlers - Field handlers map
+ * @returns {Promise<Array>} Daily analytics for the year (up to 365/366 records)
+ */
+export async function getYearByDay(resourceName, field, year, options, fieldHandlers) {
+  const startDate = `${year}-01-01`;
+  const endDate = `${year}-12-31`;
+
+  const data = await getAnalytics(resourceName, field, {
+    period: 'day',
+    startDate,
+    endDate
+  }, fieldHandlers);
+
+  if (options.fillGaps) {
+    return fillGaps(data, 'day', startDate, endDate);
+  }
+
+  return data;
+}
+
+/**
+ * Get analytics for entire week, broken down by days
+ *
+ * @param {string} resourceName - Resource name
+ * @param {string} field - Field name
+ * @param {string} week - Week in YYYY-Www format (e.g., '2025-W42')
+ * @param {Object} options - Options
+ * @param {Object} fieldHandlers - Field handlers map
+ * @returns {Promise<Array>} Daily analytics for the week (7 records)
+ */
+export async function getWeekByDay(resourceName, field, week, options, fieldHandlers) {
+  // week format: '2025-W42'
+  const year = parseInt(week.substring(0, 4));
+  const weekNum = parseInt(week.substring(6, 8));
+
+  // Calculate the first day of the week (Monday) using ISO 8601 - use UTC
+  const jan4 = new Date(Date.UTC(year, 0, 4));
+  const jan4Day = jan4.getUTCDay() || 7; // Sunday = 7
+  const firstMonday = new Date(Date.UTC(year, 0, 4 - jan4Day + 1));
+  const weekStart = new Date(firstMonday);
+  weekStart.setUTCDate(weekStart.getUTCDate() + (weekNum - 1) * 7);
+
+  // Get all 7 days of the week
+  const days = [];
+  for (let i = 0; i < 7; i++) {
+    const day = new Date(weekStart);
+    day.setUTCDate(weekStart.getUTCDate() + i);
+    days.push(day.toISOString().substring(0, 10));
+  }
+
+  const startDate = days[0];
+  const endDate = days[6];
+
+  const data = await getAnalytics(resourceName, field, {
+    period: 'day',
+    startDate,
+    endDate
+  }, fieldHandlers);
+
+  if (options.fillGaps) {
+    return fillGaps(data, 'day', startDate, endDate);
+  }
+
+  return data;
+}
+
+/**
+ * Get analytics for entire week, broken down by hours
+ *
+ * @param {string} resourceName - Resource name
+ * @param {string} field - Field name
+ * @param {string} week - Week in YYYY-Www format (e.g., '2025-W42')
+ * @param {Object} options - Options
+ * @param {Object} fieldHandlers - Field handlers map
+ * @returns {Promise<Array>} Hourly analytics for the week (168 records)
+ */
+export async function getWeekByHour(resourceName, field, week, options, fieldHandlers) {
+  // week format: '2025-W42'
+  const year = parseInt(week.substring(0, 4));
+  const weekNum = parseInt(week.substring(6, 8));
+
+  // Calculate the first day of the week (Monday) using ISO 8601 - use UTC
+  const jan4 = new Date(Date.UTC(year, 0, 4));
+  const jan4Day = jan4.getUTCDay() || 7; // Sunday = 7
+  const firstMonday = new Date(Date.UTC(year, 0, 4 - jan4Day + 1));
+  const weekStart = new Date(firstMonday);
+  weekStart.setUTCDate(weekStart.getUTCDate() + (weekNum - 1) * 7);
+
+  // Get first and last day of week
+  const weekEnd = new Date(weekStart);
+  weekEnd.setUTCDate(weekEnd.getUTCDate() + 6);
+
+  const startDate = weekStart.toISOString().substring(0, 10);
+  const endDate = weekEnd.toISOString().substring(0, 10);
+
+  const data = await getAnalytics(resourceName, field, {
+    period: 'hour',
+    startDate,
+    endDate
+  }, fieldHandlers);
+
+  if (options.fillGaps) {
+    return fillGaps(data, 'hour', startDate, endDate);
+  }
+
+  return data;
+}
+
+/**
+ * Get analytics for last N hours
+ *
+ * @param {string} resourceName - Resource name
+ * @param {string} field - Field name
+ * @param {number} hours - Number of hours to look back (default: 24)
+ * @param {Object} options - Options
+ * @param {Object} fieldHandlers - Field handlers map
+ * @returns {Promise<Array>} Hourly analytics
+ */
+export async function getLastNHours(resourceName, field, hours = 24, options, fieldHandlers) {
+  const now = new Date();
+  const hoursAgo = new Date(now);
+  hoursAgo.setHours(hoursAgo.getHours() - hours + 1); // +1 to include current hour
+
+  const startHour = hoursAgo.toISOString().substring(0, 13); // YYYY-MM-DDTHH
+  const endHour = now.toISOString().substring(0, 13);
+
+  const data = await getAnalytics(resourceName, field, {
+    period: 'hour',
+    startDate: startHour,
+    endDate: endHour
+  }, fieldHandlers);
+
+  if (options.fillGaps) {
+    // For hour-level gaps, we need to manually generate the exact hours requested
+    const result = [];
+    const emptyRecord = { count: 0, sum: 0, avg: 0, min: 0, max: 0, recordCount: 0 };
+    const dataMap = new Map(data.map(d => [d.cohort, d]));
+
+    const current = new Date(hoursAgo);
+    for (let i = 0; i < hours; i++) {
+      const cohort = current.toISOString().substring(0, 13);
+      result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });
+      current.setHours(current.getHours() + 1);
+    }
+
+    return result;
+  }
+
+  return data;
+}
+
+/**
+ * Get analytics for last N weeks
+ *
+ * @param {string} resourceName - Resource name
+ * @param {string} field - Field name
+ * @param {number} weeks - Number of weeks to look back (default: 4)
+ * @param {Object} options - Options
+ * @param {Object} fieldHandlers - Field handlers map
+ * @returns {Promise<Array>} Weekly analytics
+ */
+export async function getLastNWeeks(resourceName, field, weeks = 4, options, fieldHandlers) {
+  const now = new Date();
+  const weeksAgo = new Date(now);
+  weeksAgo.setDate(weeksAgo.getDate() - (weeks * 7));
+
+  // Get week cohorts for the range
+  const weekCohorts = [];
+  const currentDate = new Date(weeksAgo);
+  while (currentDate <= now) {
+    const weekCohort = getCohortWeekFromDate(currentDate);
+    if (!weekCohorts.includes(weekCohort)) {
+      weekCohorts.push(weekCohort);
+    }
+    currentDate.setDate(currentDate.getDate() + 7);
+  }
+
+  const startWeek = weekCohorts[0];
+  const endWeek = weekCohorts[weekCohorts.length - 1];
+
+  const data = await getAnalytics(resourceName, field, {
+    period: 'week',
+    startDate: startWeek,
+    endDate: endWeek
+  }, fieldHandlers);
+
+  return data;
+}
+
+/**
+ * Get analytics for last N months
+ *
+ * @param {string} resourceName - Resource name
+ * @param {string} field - Field name
+ * @param {number} months - Number of months to look back (default: 12)
+ * @param {Object} options - Options
+ * @param {Object} fieldHandlers - Field handlers map
+ * @returns {Promise<Array>} Monthly analytics
+ */
+export async function getLastNMonths(resourceName, field, months = 12, options, fieldHandlers) {
+  const now = new Date();
+  const monthsAgo = new Date(now);
+  monthsAgo.setMonth(monthsAgo.getMonth() - months + 1); // +1 to include current month
+
+  const startDate = monthsAgo.toISOString().substring(0, 7); // YYYY-MM
+  const endDate = now.toISOString().substring(0, 7);
+
+  const data = await getAnalytics(resourceName, field, {
+    period: 'month',
+    startDate,
+    endDate
+  }, fieldHandlers);
+
+  if (options.fillGaps) {
+    // Generate exact months requested
+    const result = [];
+    const emptyRecord = { count: 0, sum: 0, avg: 0, min: 0, max: 0, recordCount: 0 };
+    const dataMap = new Map(data.map(d => [d.cohort, d]));
+
+    const current = new Date(monthsAgo);
+    for (let i = 0; i < months; i++) {
+      const cohort = current.toISOString().substring(0, 7);
+      result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });
+      current.setMonth(current.getMonth() + 1);
+    }
+
+    return result;
+  }
+
+  return data;
+}

package/src/plugins/eventual-consistency/index.js

@@ -17,7 +17,7 @@ import {
   runConsolidation
 } from "./consolidation.js";
 import { runGarbageCollection } from "./garbage-collection.js";
-import { updateAnalytics, getAnalytics, getMonthByDay, getDayByHour, getLastNDays, getYearByMonth, getYearByWeek, getMonthByWeek, getMonthByHour, getTopRecords } from "./analytics.js";
+import { updateAnalytics, getAnalytics, getMonthByDay, getDayByHour, getLastNDays, getYearByMonth, getYearByWeek, getMonthByWeek, getMonthByHour, getTopRecords, getYearByDay, getWeekByDay, getWeekByHour, getLastNHours, getLastNWeeks, getLastNMonths } from "./analytics.js";
 import { onInstall, onStart, onStop, watchForResource, completeFieldSetup } from "./install.js";
 
 export class EventualConsistencyPlugin extends Plugin {
@@ -459,6 +459,78 @@ export class EventualConsistencyPlugin extends Plugin {
   async getTopRecords(resourceName, field, options = {}) {
     return await getTopRecords(resourceName, field, options, this.fieldHandlers);
   }
+
+  /**
+   * Get analytics for entire year, broken down by days
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} year - Year (e.g., 2025)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Daily analytics for the year (up to 365/366 records)
+   */
+  async getYearByDay(resourceName, field, year, options = {}) {
+    return await getYearByDay(resourceName, field, year, options, this.fieldHandlers);
+  }
+
+  /**
+   * Get analytics for entire week, broken down by days
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {string} week - Week in YYYY-Www format (e.g., '2025-W42')
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Daily analytics for the week (7 records)
+   */
+  async getWeekByDay(resourceName, field, week, options = {}) {
+    return await getWeekByDay(resourceName, field, week, options, this.fieldHandlers);
+  }
+
+  /**
+   * Get analytics for entire week, broken down by hours
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {string} week - Week in YYYY-Www format (e.g., '2025-W42')
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Hourly analytics for the week (168 records)
+   */
+  async getWeekByHour(resourceName, field, week, options = {}) {
+    return await getWeekByHour(resourceName, field, week, options, this.fieldHandlers);
+  }
+
+  /**
+   * Get analytics for last N hours
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} hours - Number of hours to look back (default: 24)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Hourly analytics
+   */
+  async getLastNHours(resourceName, field, hours = 24, options = {}) {
+    return await getLastNHours(resourceName, field, hours, options, this.fieldHandlers);
+  }
+
+  /**
+   * Get analytics for last N weeks
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} weeks - Number of weeks to look back (default: 4)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Weekly analytics
+   */
+  async getLastNWeeks(resourceName, field, weeks = 4, options = {}) {
+    return await getLastNWeeks(resourceName, field, weeks, options, this.fieldHandlers);
+  }
+
+  /**
+   * Get analytics for last N months
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} months - Number of months to look back (default: 12)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Monthly analytics
+   */
+  async getLastNMonths(resourceName, field, months = 12, options = {}) {
+    return await getLastNMonths(resourceName, field, months, options, this.fieldHandlers);
+  }
 }
 
 export default EventualConsistencyPlugin;