hearald 0.0.3 → 0.0.5

package/.prettierignore

@@ -0,0 +1,9 @@
+.env
+.data
+.DS_Store
+node_modules
+.lesshst
+.sqlite_history
+*.md
+.github
+dist/

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.5] - 2025-10-05
+
+### Added
+
+- Export `errorMiddlware`, `trackServerEvent`, `trackServerError` as part of default `hearald` in `src/index.js'
+
+### Fixed
+
+- Bugfix to restore intra-day timestamp granularity of events.
+- Percent formatted numbers now use proper formatter
+
+### Changed
+
+- All server-side configuration parameters are defined in `src/server/configuration.js`
+
+## [0.0.4] - 2025-09-21
+
+### Changed
+
+- Use package.json `exports`
+
+## [0.0.3] - 2025-09-19
+
+### Added
+
+- Initial release of Hearald
+
+[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
+[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.3
+
+<!--
+`Added` for new features.
+`Changed` for changes in existing functionality.
+`Deprecated` for soon-to-be removed features.
+`Removed` for now removed features.
+`Fixed` for any bug fixes.
+`Security` in case of vulnerabilities.
+-->

package/dist/analytics.html

@@ -134,7 +134,7 @@ th {
 @media screen and (max-width: 640px) {
   body {
     font-size: 12px;
-    font-feature-settings: 'lnum';
+    font-feature-settings: "lnum";
   }
 }
 
@@ -264,7 +264,7 @@ th {
   word-break: keep-all;
 }
 .bar-chart__bar__label:after {
-  content: '';
+  content: "";
   width: 12px;
   height: 12px;
   background: var(--color-label);
@@ -915,8 +915,8 @@ th {
                             type="${f.type}"
                             value=${deepGet(stats.metrics, f.key)}
                             span=${f.span || null}
-                            ${f.type === "percent" ? "percent" : ""}
-                            ${f.type === "histogram" ? "histogram" : ""}
+                            percent=${f.type === "percent"}
+                            histogram=${f.type === "histogram"}
                           />
                         `;
                       })}

package/dist/index.css

@@ -122,7 +122,7 @@ th {
 @media screen and (max-width: 640px) {
   body {
     font-size: 12px;
-    font-feature-settings: 'lnum';
+    font-feature-settings: "lnum";
   }
 }
 
@@ -252,7 +252,7 @@ th {
   word-break: keep-all;
 }
 .bar-chart__bar__label:after {
-  content: '';
+  content: "";
   width: 12px;
   height: 12px;
   background: var(--color-label);

package/dist/index.js

@@ -517,8 +517,8 @@
                             type="${f.type}"
                             value=${deepGet(stats.metrics, f.key)}
                             span=${f.span || null}
-                            ${f.type === "percent" ? "percent" : ""}
-                            ${f.type === "histogram" ? "histogram" : ""}
+                            percent=${f.type === "percent"}
+                            histogram=${f.type === "histogram"}
                           />
                         `;
                       })}

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "hearald",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A single server drop-in file system based metrics and analytics library.",
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js"
+  },
   "type": "module",
   "scripts": {
     "build": "rollup --config"

package/src/index.js

@@ -1,14 +1,31 @@
-import log from "./server/logger.js";
-import { eventEndpointMiddleware, shutDown } from "./server/server.js";
+import hearaldConfiguration from "./server/configuration.js";
+
+import {
+  eventEndpointMiddleware,
+  trackServerEvent,
+  trackServerError,
+  errorTrackingMiddleware,
+  shutDown,
+} from "./server/server.js";
 import { createAnalyticsRouter } from "./server/analytics.js";
 
 export default function hearald({
+  /* singleton configuration options */
   logLevel,
+  nowFn /* () => nowAsDateString */,
+  getUserId /* (req) => userId */,
+
   eventEndpoint: { url = "/e", parseBody } = {},
   analytics: { enabled: analyticsEnabled = true, statDefinitions } = {},
 } = {}) {
   if (logLevel) {
-    log.setLogLevel(logLevel);
+    hearaldConfiguration.setLogLevel(logLevel);
+  }
+  if (nowFn) {
+    hearaldConfiguration.setNowFn(nowFn);
+  }
+  if (getUserId) {
+    hearaldConfiguration.setGetUserId(getUserId);
   }
 
   const eventMiddleware = eventEndpointMiddleware({ url, parseBody });
@@ -17,9 +34,14 @@ export default function hearald({
     ? createAnalyticsRouter({ statDefinitions })
     : null;
 
+  const errorMiddlware = errorTrackingMiddleware({});
+
   return {
-    eventMiddleware,
-    analyticsMiddleware,
+    errorMiddlware /* app.use(errorMiddlware) */,
+    eventMiddleware /* app.use(eventMiddleware) */,
+    analyticsMiddleware /* app.use('/analytics', analyticsMiddleware) */,
+    trackServerEvent /* ({ event, time = null, userId, params = {} }) => Promise } */,
+    trackServerError /* ({ error, userId = null, extraParams = {} }) => Promise } */,
     shutDown,
   };
 }

package/src/public/css/analytics.css

@@ -122,7 +122,7 @@ th {
 @media screen and (max-width: 640px) {
   body {
     font-size: 12px;
-    font-feature-settings: 'lnum';
+    font-feature-settings: "lnum";
   }
 }
 
@@ -252,7 +252,7 @@ th {
   word-break: keep-all;
 }
 .bar-chart__bar__label:after {
-  content: '';
+  content: "";
   width: 12px;
   height: 12px;
   background: var(--color-label);

package/src/public/js/App.js

@@ -303,8 +303,8 @@ class App extends Component {
                             type="${f.type}"
                             value=${deepGet(stats.metrics, f.key)}
                             span=${f.span || null}
-                            ${f.type === "percent" ? "percent" : ""}
-                            ${f.type === "histogram" ? "histogram" : ""}
+                            percent=${f.type === "percent"}
+                            histogram=${f.type === "histogram"}
                           />
                         `;
                       })}

package/src/server/analytics.js

@@ -5,12 +5,8 @@ import { fileURLToPath } from "url";
 import { readFile, writeFile } from "fs/promises";
 import express from "express";
 import log from "./logger.js";
-import {
-  omitProperties,
-  iso,
-  defaultEndDate,
-  nowAsPstDate,
-} from "../shared/utils.js";
+import hearaldConfiguration from "./configuration.js";
+import { omitProperties, defaultEndDate } from "../shared/utils.js";
 import { loadEventsOverWindow } from "./serverEvents.js";
 
 export function generateRawMetrics(events, rawMetricDefinitions) {
@@ -106,7 +102,8 @@ export function generateComputedMetric(metrics, definition, timeWindow) {
 }
 
 export function cacheFilePath(endDate, timeWindow) {
-  const endDateIso = typeof endDate === "string" ? endDate : iso(endDate);
+  const endDateIso =
+    typeof endDate === "string" ? endDate : hearaldConfiguration.isoFn(endDate);
   return `events/summary:${endDateIso}:${timeWindow}.json`;
 }
 
@@ -213,7 +210,7 @@ export async function generateStats(statDefinitions, endDate, timeWindow) {
   });
   return {
     metrics: nestedMetrics,
-    endDate: iso(endDate),
+    endDate: hearaldConfiguration.isoFn(endDate),
     timeWindow,
     processedEventCount: allEvents.length,
   };
@@ -224,7 +221,7 @@ export async function handleAnalyticsDataRequest({
   response,
   statDefinitions,
 }) {
-  const defaultEndDateIso = iso(defaultEndDate(nowAsPstDate));
+  const defaultEndDateIso = hearaldConfiguration.isoFn(defaultEndDate());
   const endDateIso = request.params.date
     ? request.params.date
     : defaultEndDateIso;
@@ -282,7 +279,6 @@ export function createAnalyticsRouter({ statDefinitions }) {
       response,
       statDefinitions,
       loadEventsOverWindow,
-      nowAsPstDate,
     });
   });
 

package/src/server/configuration.js

@@ -0,0 +1,33 @@
+import { iso, nowAsPstDate } from "../shared/utils.js";
+
+class Configuration {
+  constructor({
+    nowFn = nowAsPstDate,
+    isoFn = iso,
+    logLevel = "info",
+    getUserId = (req) => req.user?.id,
+  } = {}) {
+    this.nowFn = nowFn;
+    this.isoFn = isoFn;
+    this.logLevel = logLevel;
+    this.getUserId = getUserId;
+  }
+
+  setLogLevel(level) {
+    this.logLevel = level;
+  }
+
+  setNowFn(nowFn) {
+    this.nowFn = nowFn;
+  }
+
+  setGetUserId(getUserId) {
+    this.getUserId = getUserId;
+  }
+
+  setIsoFn(isoFn) {
+    this.isoFn = isoFn;
+  }
+}
+
+export default new Configuration();

package/src/server/logger.js

@@ -1,26 +1,24 @@
-class Logger {
-  constructor(level) {
-    this.level = level || "info";
-  }
+import hearaldConfiguration from "./configuration.js";
 
-  setLogLevel(level) {
-    this.level = level;
+class Logger {
+  constructor(config = hearaldConfiguration) {
+    this.config = config;
   }
 
   debug(...args) {
-    if (this.level === "debug") {
+    if (this.config.logLevel === "debug") {
       console.log("[DEBUG]", ...args);
     }
   }
 
   info(...args) {
-    if (this.level === "debug" || this.level === "info") {
+    if (this.config.logLevel === "debug" || this.config.logLevel === "info") {
       console.log("[INFO]", ...args);
     }
   }
 
   warn(...args) {
-    if (this.level !== "error") {
+    if (this.config.logLevel !== "error") {
       console.warn("[WARN]", ...args);
     }
   }

package/src/server/server.js

@@ -1,13 +1,9 @@
 // Express middleware for hearald event tracking
 import express from "express";
-import log from "./logger.js";
-import { nowAsPstDate } from "../shared/utils.js";
-import { writeEvent, closeEventFiles } from "./serverEvents.js";
-import { createAnalyticsRouter } from "./analytics.js";
 
-export async function logEvent(time, event) {
-  return writeEvent(time, event);
-}
+import hearaldConfiguration from "./configuration.js";
+import log from "./logger.js";
+import { writeEvent, closeEventFiles, VISIT_EVENT } from "./serverEvents.js";
 
 export async function shutDown() {
   await closeEventFiles();
@@ -29,11 +25,11 @@ export function eventEndpointMiddleware({ url = "/e", parseBody } = {}) {
         ({ e, u, p } = parseBody(req));
       } else {
         ({ e = null, u = null, p = {} } = req.body || {});
-        if (e === "visit") {
+        if (e === VISIT_EVENT) {
           p.ip = req.ip;
         }
       }
-      await logEvent(nowAsPstDate(), { e, u, p });
+      await writeEvent(hearaldConfiguration.nowFn(), { e, u, p });
     } catch (err) {
       // eslint-disable-next-line no-console
       log.error("error writing event to event log", err);
@@ -42,3 +38,57 @@ export function eventEndpointMiddleware({ url = "/e", parseBody } = {}) {
   });
   return router;
 }
+
+export async function trackServerEvent({
+  event,
+  time = null,
+  userId,
+  params = {},
+}) {
+  await writeEvent(time || hearaldConfiguration.nowFn(), {
+    e: event,
+    u: userId,
+    p: params,
+  });
+}
+
+export async function trackServerError({
+  error,
+  userId = null,
+  extraParams = {},
+}) {
+  let message = "";
+  let stack = "";
+  if (error instanceof Error) {
+    message = error.message;
+    stack = error.stack || "";
+  } else if (typeof error === "string") {
+    message = error;
+  } else if (error && typeof error === "object") {
+    message = error.message || JSON.stringify(error);
+    stack = error.stack || "";
+  }
+  const params = {
+    message,
+    stack,
+    ...extraParams,
+  };
+  await writeEvent(hearaldConfiguration.nowFn(), {
+    e: ERROR_EVENT,
+    u: userId,
+    p: params,
+  });
+}
+
+// Express error-handling middleware
+export function errorTrackingMiddleware({}) {
+  // eslint-disable-next-line no-unused-vars
+  return function (err, req, res, next) {
+    trackServerError({
+      error: err,
+      userId: hearaldConfiguration.getUserId(req),
+      extraParams: { url: req.originalUrl, method: req.method, ip: req.ip },
+    });
+    next(err);
+  };
+}

package/src/server/serverEvents.js

@@ -1,7 +1,10 @@
 import { readFile, open as openFile, mkdir } from "fs/promises";
 
+import hearaldConfiguration from "./configuration.js";
 import log from "./logger.js";
-import { iso } from "../shared/utils.js";
+
+export const VISIT_EVENT = "visit";
+export const ERROR_EVENT = "error";
 
 const eventFilePromises = new Map();
 const lastWriteTimeouts = new Map();
@@ -11,14 +14,14 @@ export const openEventFile = async (fileName) => {
   return openFile(`events/${fileName}.log`, "a");
 };
 
-export const writeEvent = async (time, event, isoFn = iso) => {
+export const writeEvent = async (time, event) => {
   let fileName;
 
-  const dateString = isoFn(time);
+  const dateString = hearaldConfiguration.isoFn(time);
 
-  if (event.e === "visit") {
+  if (event.e === VISIT_EVENT) {
     fileName = `${dateString}-visits`;
-  } else if (event.e === "error") {
+  } else if (event.e === ERROR_EVENT) {
     fileName = `${dateString}-errors`;
   } else {
     fileName = dateString;
@@ -91,12 +94,12 @@ export const readEventsFromFile = async (fileName) => {
   }
 };
 
-export const loadEventsOverWindow = async (d, n, fileSuffix, isoFn = iso) => {
+export const loadEventsOverWindow = async (d, n, fileSuffix) => {
   let events = [];
   for (let i = 0; i < n; i++) {
     const newDate = new Date(d);
     newDate.setDate(d.getDate() - i);
-    let fileName = isoFn(newDate);
+    let fileName = hearaldConfiguration.isoFn(newDate);
     if (fileSuffix) {
       fileName += `-${fileSuffix}`;
     }

package/src/shared/utils.js

@@ -10,8 +10,8 @@ export const pacificTimeFormatter = new Intl.DateTimeFormat("en-US", {
 export const pacificTimeOffsetHours = (date) =>
   pacificTimeFormatter.format(date || new Date()).endsWith("PDT") ? -7 : -8;
 
-export const dateStringToPstDate = (dateString) => {
-  const rawDate = dateString ? new Date(dateString) : new Date();
+export const nowAsPstDate = () => {
+  const rawDate = new Date();
   const offset = pacificTimeOffsetHours(rawDate);
   const pstDate = new Date();
   pstDate.setUTCFullYear(
@@ -19,12 +19,10 @@ export const dateStringToPstDate = (dateString) => {
     rawDate.getUTCMonth(),
     rawDate.getUTCDate()
   );
-  pstDate.setUTCHours(-1 * offset, 0, 0, 0);
+  pstDate.setUTCHours(-1 * offset);
   return pstDate;
 };
 
-export const nowAsPstDate = () => dateStringToPstDate();
-
 export function omitProperties(object, ...keys) {
   let rest = object;
   keys.forEach((key) => {

package/src/server/serverTrackError.js

@@ -1,47 +0,0 @@
-// hearald/src/serverTrackError.js
-// Server-side utility to track errors
-
-export async function trackServerError({
-  error,
-  logEvent,
-  userId = null,
-  extraParams = {},
-  nowFn = () => new Date(),
-}) {
-  let message = "";
-  let stack = "";
-  if (error instanceof Error) {
-    message = error.message;
-    stack = error.stack || "";
-  } else if (typeof error === "string") {
-    message = error;
-  } else if (error && typeof error === "object") {
-    message = error.message || JSON.stringify(error);
-    stack = error.stack || "";
-  }
-  const params = {
-    message,
-    stack,
-    ...extraParams,
-  };
-  await logEvent(nowFn(), { e: "error", u: userId, p: params });
-}
-
-// Express error-handling middleware
-export function errorTrackingMiddleware({
-  logEvent,
-  nowFn = () => new Date(),
-  userIdExtractor = (req) => req.user?.id,
-}) {
-  // eslint-disable-next-line no-unused-vars
-  return function (err, req, res, next) {
-    trackServerError({
-      error: err,
-      logEvent,
-      userId: userIdExtractor(req),
-      extraParams: { url: req.originalUrl, method: req.method, ip: req.ip },
-      nowFn,
-    });
-    next(err);
-  };
-}