@lovelaces-io/storyteller 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -22,11 +22,11 @@ var index_exports = {};
 __export(index_exports, {
   ANSI: () => ANSI,
   Storyteller: () => Storyteller,
-  colorizeJsonSections: () => colorizeJsonSections,
   consoleAudience: () => consoleAudience,
-  countBrackets: () => countBrackets,
   dbAudience: () => dbAudience,
+  formatDuration: () => formatDuration,
   formatOrigin: () => formatOrigin,
+  formatStory: () => formatStory,
   getLevelColor: () => getLevelColor,
   summarizeStory: () => summarizeStory,
   useStoryteller: () => useStoryteller,
@@ -34,6 +34,28 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/audiences/consoleAudience.ts
+function consoleAudience() {
+  return {
+    name: "console",
+    hear: (event) => {
+      const prefix = "Storyteller";
+      const style = event.level === "Information" ? "color:#16a34a;font-weight:600" : event.level === "Warning" ? "color:#f59e0b;font-weight:600" : "color:#dc2626;font-weight:600";
+      const header = `${prefix}: ${event.title}`;
+      console.groupCollapsed(`%c${header}`, style);
+      const payload = JSON.stringify(event, null, 2);
+      if (event.level === "Information") {
+        console.log(header, payload);
+      } else if (event.level === "Warning") {
+        console.warn(header, payload);
+      } else {
+        console.error(header, payload);
+      }
+      console.groupEnd();
+    }
+  };
+}
+
 // src/utils.ts
 var ANSI = {
   reset: "\x1B[0m",
@@ -41,18 +63,21 @@ var ANSI = {
   yellow: "\x1B[33m",
   red: "\x1B[38;2;250;128;114m",
   grayLight: "\x1B[37m",
-  grayDark: "\x1B[37m"
+  grayDark: "\x1B[90m"
 };
 function getLevelColor(level) {
-  if (level === "tell") return ANSI.green;
-  if (level === "warn") return ANSI.yellow;
+  if (level === "Information") return ANSI.green;
+  if (level === "Warning") return ANSI.yellow;
   return ANSI.red;
 }
 function formatOrigin(origin) {
   if (!origin?.where) return;
   if (typeof origin.where === "string") return origin.where;
   const whereRecord = origin.where;
-  const parts = [whereRecord.app, whereRecord.service, whereRecord.page, whereRecord.component].filter(Boolean).map(String);
+  const priorityKeys = ["app", "service", "page", "component"];
+  const priorityParts = priorityKeys.filter((key) => whereRecord[key] != null).map((key) => String(whereRecord[key]));
+  const extraParts = Object.entries(whereRecord).filter(([key, value]) => !priorityKeys.includes(key) && value != null).map(([_, value]) => String(value));
+  const parts = [...priorityParts, ...extraParts];
   return parts.length ? parts.join(" / ") : void 0;
 }
 function colorizeJsonSections(json, colors) {
@@ -80,27 +105,144 @@ function countBrackets(line) {
   return openCount - closeCount;
 }
 
-// src/audiences/consoleAudience.ts
-function consoleAudience() {
-  return {
-    name: "console",
-    hear: (event) => {
-      const prefix = "Storyteller";
-      const style = event.level === "tell" ? "color:#16a34a;font-weight:600" : event.level === "warn" ? "color:#f59e0b;font-weight:600" : "color:#dc2626;font-weight:600";
-      const header = `${prefix}: ${event.title}`;
-      console.groupCollapsed(`%c${header}`, style);
-      const payload = JSON.stringify(event, null, 2);
-      const coloredPayload = event.level === "oops" ? `${ANSI.red}${payload}${ANSI.reset}` : payload;
-      if (event.level === "tell") {
-        console.log(header, payload);
-      } else if (event.level === "warn") {
-        console.warn(header, payload);
-      } else {
-        console.error(header, coloredPayload);
-      }
-      console.groupEnd();
-    }
+// src/formatting.ts
+function formatStory(story, options = {}) {
+  const {
+    timezone = Intl.DateTimeFormat().resolvedOptions().timeZone,
+    locale = "en-US",
+    detail = "normal",
+    noteLimit = 50,
+    showData = true,
+    colors = true
+  } = options;
+  const dateTimeFormatter = new Intl.DateTimeFormat(locale, {
+    timeZone: timezone,
+    year: "numeric",
+    month: "short",
+    day: "2-digit",
+    hour: "numeric",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+  const timeFormatter = new Intl.DateTimeFormat(locale, {
+    timeZone: timezone,
+    hour: "numeric",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+  const orderedNotes = [...story.notes].sort(
+    (noteA, noteB) => Date.parse(noteA.timestamp) - Date.parse(noteB.timestamp)
+  );
+  const durationMs = story.durationMs ?? calculateNoteDuration(orderedNotes);
+  const duration = durationMs != null ? formatDuration(durationMs) : void 0;
+  const slicedNotes = orderedNotes.slice(0, noteLimit);
+  const reportNotes = slicedNotes.map((note) => ({
+    timestamp: note.timestamp,
+    when: timeFormatter.format(new Date(note.timestamp)),
+    note: note.note,
+    text: formatNoteText(note, detail),
+    ...note.who ? { who: note.who } : {},
+    ...note.what ? { what: note.what } : {},
+    ...note.where ? { where: note.where } : {},
+    ...note.error ? { error: note.error } : {}
+  }));
+  const data = {
+    title: story.title,
+    level: story.level,
+    when: dateTimeFormatter.format(new Date(story.timestamp)),
+    ...durationMs != null ? { durationMs } : {},
+    ...duration ? { duration } : {},
+    ...story.origin ? { origin: story.origin } : {},
+    notes: reportNotes,
+    ...story.error ? { error: story.error } : {}
   };
+  const lines = buildReportText(story, data, reportNotes, orderedNotes, {
+    colors,
+    detail,
+    showData,
+    duration
+  });
+  return { text: lines.join("\n"), data };
+}
+function buildReportText(story, data, reportNotes, orderedNotes, options) {
+  const levelColor = getLevelColor(story.level);
+  const label = (text) => options.colors ? `${levelColor}${text}${ANSI.reset}` : text;
+  const originLabel = formatOrigin(story.origin);
+  const lines = [];
+  lines.push(`${label("Story")}: ${story.title}`);
+  lines.push(`${label("Level")}: ${story.level}`);
+  lines.push(`${label("Time")}: ${data.when}${options.duration ? ` (${options.duration})` : ""}`);
+  if (originLabel) {
+    lines.push(`${label("Origin")}: ${originLabel}`);
+  }
+  if (story.error) {
+    const errorLine = [story.error.name, story.error.message].filter(Boolean).join(": ");
+    if (errorLine) lines.push(`${label("Error")}: ${errorLine}`);
+  }
+  if (options.detail !== "brief" && reportNotes.length) {
+    lines.push(`${label("Notes")}:`);
+    for (const note of reportNotes) {
+      lines.push(`  ${note.when} \u2014 ${note.text}`);
+    }
+    if (orderedNotes.length > reportNotes.length) {
+      lines.push(`  \u2026 (${orderedNotes.length - reportNotes.length} more)`);
+    }
+  }
+  if (options.showData) {
+    lines.push(`${label("Data")}:`);
+    const json = JSON.stringify(data, null, 2);
+    if (options.colors) {
+      const colored = colorizeJsonSections(json, {
+        base: ANSI.grayLight,
+        notes: ANSI.grayDark,
+        reset: ANSI.reset
+      });
+      lines.push(...colored);
+    } else {
+      lines.push(...json.split("\n"));
+    }
+  }
+  return lines;
+}
+function calculateNoteDuration(notes) {
+  if (notes.length <= 1) return void 0;
+  const startTime = Date.parse(notes[0].timestamp);
+  const endTime = Date.parse(notes[notes.length - 1].timestamp);
+  return Number.isFinite(startTime) && Number.isFinite(endTime) ? Math.max(0, endTime - startTime) : void 0;
+}
+function formatDuration(milliseconds) {
+  if (milliseconds < 1e3) return `${milliseconds}ms`;
+  const seconds = milliseconds / 1e3;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = Math.round(seconds % 60).toString().padStart(2, "0");
+  return `${minutes}:${remainingSeconds}m`;
+}
+var summarizeStory = formatStory;
+function formatNoteText(note, verbosity) {
+  if (verbosity !== "full") return note.note;
+  const details = [];
+  const what = note.what;
+  const where = note.where;
+  if (typeof what === "string") {
+    details.push(`what=${what}`);
+  } else if (what) {
+    for (const [key, value] of Object.entries(what)) {
+      if (value != null) details.push(`${key}=${String(value)}`);
+    }
+  }
+  if (typeof where === "string") {
+    details.push(`where=${where}`);
+  } else if (where) {
+    for (const [key, value] of Object.entries(where)) {
+      if (value != null) details.push(`${key}=${String(value)}`);
+    }
+  }
+  if (note.error) {
+    const errorLine = [note.error.name, note.error.message].filter(Boolean).join(": ");
+    if (errorLine) details.push(`error=${errorLine}`);
+  }
+  return details.length ? `${note.note} (${details.join(" ")})` : note.note;
 }
 
 // src/storyteller.ts
@@ -124,6 +266,14 @@ var AudienceRegistry = class {
   getOnly(names) {
     return names.map((name) => this.members.get(name)).filter(Boolean);
   }
+  /** Check if an audience member is registered by name */
+  has(name) {
+    return this.members.has(name);
+  }
+  /** List the names of all registered audience members */
+  names() {
+    return [...this.members.keys()];
+  }
 };
 var Storyteller = class {
   audience = new AudienceRegistry();
@@ -134,7 +284,17 @@ var Storyteller = class {
     this.audience.add(consoleAudience());
     options?.audiences?.forEach((audience) => this.audience.add(audience));
   }
-  /** Add a timestamped note with optional context (who, what, where, error) */
+  /**
+   * Add a timestamped note to the current story.
+   * @param text - What happened
+   * @param data - Optional context: who did it, what was involved, where it happened, any error
+   * @returns `this` for chaining
+   *
+   * @example
+   * ```ts
+   * story.note("Card charged", { what: { amount: "$42" }, where: "stripe" });
+   * ```
+   */
   note(text, data = {}) {
     this.notes.push({
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -151,13 +311,13 @@ var Storyteller = class {
     this.notes = [];
     return this;
   }
-  /** Generate a formatted summary of current notes without emitting or clearing them */
+  /** Preview the current notes as a formatted report without emitting or clearing them */
   summarize(options = {}) {
     const {
       title = "Story preview",
-      level = "tell",
+      level = "Information",
       error,
-      ...summaryOptions
+      ...reportOptions
     } = options;
     const event = {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -167,23 +327,23 @@ var Storyteller = class {
       notes: [...this.notes],
       ...error ? { error: normalizeError(error) } : {}
     };
-    return summarizeStory(event, summaryOptions);
+    return formatStory(event, reportOptions);
   }
-  /** Emit a story at the "tell" level (success / informational) */
+  /** Tell a success story — everything went well */
   tell(title) {
     return this.createDelivery("tell", title);
   }
-  /** Emit a story at the "warn" level (something was off) */
+  /** Tell a cautionary story — something was off but it's handled */
   warn(title) {
     return this.createDelivery("warn", title);
   }
-  /** Emit a story at the "oops" level (something broke) with an optional error */
+  /** Tell an error story — something broke. Pass the error for automatic normalization. */
   oops(title, error) {
     return this.createDelivery("oops", title, error);
   }
   /** Build a story event and schedule delivery, returning a handle to override the audience list */
-  createDelivery(level, title, error) {
-    const event = this.buildEvent(level, title, error);
+  createDelivery(method, title, error) {
+    const event = this.buildEvent(method, title, error);
     let delivered = false;
     let defaultCancelled = false;
     queueMicrotask(() => {
@@ -201,21 +361,26 @@ var Storyteller = class {
     };
   }
   /** Assemble the story event from current notes and clear notes for the next story */
-  buildEvent(level, title, error) {
+  buildEvent(method, title, error) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const collectedNotes = [...this.notes];
+    const level = methodToLevel(method);
+    const sortedNotes = [...this.notes].sort(
+      (noteA, noteB) => Date.parse(noteA.timestamp) - Date.parse(noteB.timestamp)
+    );
     this.notes = [];
+    const durationMs = calculateNoteDuration2(sortedNotes).durationMs;
     const event = {
       timestamp: now,
       level,
       title,
       ...this.origin ? { origin: this.origin } : {},
-      notes: collectedNotes,
+      notes: sortedNotes,
+      ...durationMs != null ? { durationMs } : {},
       ...error ? { error: normalizeError(error) } : {}
     };
     const eventWithSummary = event;
     Object.defineProperty(eventWithSummary, "summarize", {
-      value: (options) => summarizeStory(event, options),
+      value: (options) => formatStory(event, options),
       enumerable: false
     });
     return eventWithSummary;
@@ -228,6 +393,11 @@ var Storyteller = class {
     );
   }
 };
+function methodToLevel(method) {
+  if (method === "tell") return "Information";
+  if (method === "warn") return "Warning";
+  return "Error";
+}
 function normalizeError(rawError) {
   if (rawError instanceof Error) {
     const normalized = {
@@ -245,7 +415,7 @@ function normalizeError(rawError) {
   }
   return { message: String(rawError) };
 }
-function calculateNoteDuration(notes) {
+function calculateNoteDuration2(notes) {
   if (notes.length <= 1) {
     return {
       durationMs: void 0
@@ -257,125 +427,6 @@ function calculateNoteDuration(notes) {
     durationMs: Number.isFinite(startTime) && Number.isFinite(endTime) ? Math.max(0, endTime - startTime) : void 0
   };
 }
-function summarizeStory(story, options = {}) {
-  const {
-    timezone = Intl.DateTimeFormat().resolvedOptions().timeZone,
-    locale = "en-US",
-    verbosity = "normal",
-    maxNotes = 50,
-    showData = true,
-    colorize = true
-  } = options;
-  const dateTimeFormatter = new Intl.DateTimeFormat(locale, {
-    timeZone: timezone,
-    year: "numeric",
-    month: "short",
-    day: "2-digit",
-    hour: "numeric",
-    minute: "2-digit",
-    second: "2-digit"
-  });
-  const timeFormatter = new Intl.DateTimeFormat(locale, {
-    timeZone: timezone,
-    hour: "numeric",
-    minute: "2-digit",
-    second: "2-digit"
-  });
-  const orderedNotes = [...story.notes].sort(
-    (noteA, noteB) => Date.parse(noteA.timestamp) - Date.parse(noteB.timestamp)
-  );
-  const noteTiming = calculateNoteDuration(orderedNotes);
-  const originLabel = formatOrigin(story.origin);
-  const duration = noteTiming.durationMs != null ? formatDuration(noteTiming.durationMs) : void 0;
-  const slicedNotes = orderedNotes.slice(0, maxNotes);
-  const summaryNotes = slicedNotes.map((note) => ({
-    timestamp: note.timestamp,
-    when: timeFormatter.format(new Date(note.timestamp)),
-    note: note.note,
-    text: formatNoteText(note, verbosity),
-    ...note.who ? { who: note.who } : {},
-    ...note.what ? { what: note.what } : {},
-    ...note.where ? { where: note.where } : {},
-    ...note.error ? { error: note.error } : {}
-  }));
-  const data = {
-    title: story.title,
-    level: story.level,
-    when: dateTimeFormatter.format(new Date(story.timestamp)),
-    ...noteTiming.durationMs != null ? { durationMs: noteTiming.durationMs } : {},
-    ...duration ? { duration } : {},
-    ...story.origin ? { origin: story.origin } : {},
-    notes: summaryNotes,
-    ...story.error ? { error: story.error } : {}
-  };
-  const levelColor = getLevelColor(story.level);
-  const label = (text) => colorize ? `${levelColor}${text}${ANSI.reset}` : text;
-  const lines = [];
-  lines.push(`${label("Story")}: ${story.title}`);
-  lines.push(`${label("Level")}: ${story.level}`);
-  lines.push(`${label("Time")}: ${data.when}${duration ? ` (${duration})` : ""}`);
-  if (originLabel) {
-    lines.push(`${label("Origin")}: ${originLabel}`);
-  }
-  if (story.error) {
-    const errorLine = [story.error.name, story.error.message].filter(Boolean).join(": ");
-    if (errorLine) lines.push(`${label("Error")}: ${errorLine}`);
-  }
-  if (verbosity !== "brief" && summaryNotes.length) {
-    lines.push(`${label("Notes")}:`);
-    for (const note of summaryNotes) {
-      lines.push(`  ${note.when} \u2014 ${note.text}`);
-    }
-    if (orderedNotes.length > summaryNotes.length) {
-      lines.push(`  \u2026 (${orderedNotes.length - summaryNotes.length} more)`);
-    }
-  }
-  if (showData) {
-    lines.push(`${label("Data")}:`);
-    const json = JSON.stringify(data, null, 2);
-    if (colorize) {
-      const colored = colorizeJsonSections(json, {
-        base: ANSI.grayLight,
-        notes: ANSI.grayDark,
-        reset: ANSI.reset
-      });
-      lines.push(...colored);
-    } else {
-      lines.push(...json.split("\n"));
-    }
-  }
-  return { text: lines.join("\n"), data };
-}
-function formatDuration(milliseconds) {
-  if (milliseconds < 1e3) return `${milliseconds}ms`;
-  const seconds = milliseconds / 1e3;
-  if (seconds < 60) return `${seconds.toFixed(1)}s`;
-  const minutes = Math.floor(seconds / 60);
-  const remainingSeconds = Math.round(seconds % 60).toString().padStart(2, "0");
-  return `${minutes}:${remainingSeconds}m`;
-}
-function formatNoteText(note, verbosity) {
-  if (verbosity !== "full") return note.note;
-  const details = [];
-  const what = note.what;
-  const where = note.where;
-  if (typeof what === "string") {
-    details.push(`what=${what}`);
-  } else if (what) {
-    if (what.field) details.push(`field=${String(what.field)}`);
-    if (what.status) details.push(`status=${String(what.status)}`);
-  }
-  if (typeof where === "string") {
-    details.push(`where=${where}`);
-  } else if (where) {
-    if (where.component) details.push(`component=${String(where.component)}`);
-  }
-  if (note.error) {
-    const errorLine = [note.error.name, note.error.message].filter(Boolean).join(": ");
-    if (errorLine) details.push(`error=${errorLine}`);
-  }
-  return details.length ? `${note.note} (${details.join(" ")})` : note.note;
-}
 
 // src/useStoryteller.ts
 var sharedInstance;
@@ -391,7 +442,7 @@ function useStoryteller(options = {}) {
 function dbAudience(insert) {
   return {
     name: "db",
-    accepts: (event) => event.level === "warn" || event.level === "oops",
+    accepts: (event) => event.level === "Warning" || event.level === "Error",
     hear: async (event) => {
       await insert(event);
     }
@@ -403,10 +454,10 @@ function writeStoryReport(stories, options = {}) {
   const {
     timezone = Intl.DateTimeFormat().resolvedOptions().timeZone,
     locale = "en-US",
-    verbosity = "normal",
-    maxNotesPerStory = 50,
+    detail = "normal",
+    noteLimit = 50,
     showData = true,
-    colorize = true
+    colors = true
   } = options;
   if (!stories.length) {
     return "Storyteller Report\n\n(no stories)\n";
@@ -443,17 +494,17 @@ function writeStoryReport(stories, options = {}) {
   for (const [day, dayStories] of storiesByDay) {
     lines.push(day);
     for (const story of dayStories) {
-      const summary = summarizeStory(story, {
+      const report = formatStory(story, {
         timezone,
         locale,
-        verbosity,
-        maxNotes: maxNotesPerStory,
-        colorize
+        detail,
+        noteLimit,
+        colors
       });
-      const { data } = summary;
+      const { data } = report;
       const originLabel = formatOrigin(story.origin);
       const levelColor = getLevelColor(story.level);
-      const label = (text) => colorize ? `${levelColor}${text}${ANSI.reset}` : text;
+      const label = (text) => colors ? `${levelColor}${text}${ANSI.reset}` : text;
       const duration = data.duration ? ` (${data.duration})` : "";
       lines.push(`${label("Story")}: ${story.title}`);
       lines.push(`${label("Level")}: ${story.level}`);
@@ -468,10 +519,10 @@ function writeStoryReport(stories, options = {}) {
         ].filter(Boolean).join(": ");
         if (errorLine) lines.push(`${label("Error")}: ${errorLine}`);
       }
-      if (verbosity !== "brief" && data.notes.length) {
+      if (detail !== "brief" && data.notes.length) {
         lines.push(`  ${label("Notes")}:`);
-        for (const summaryNote of data.notes) {
-          lines.push(`    ${summaryNote.when} \u2014 ${summaryNote.text}`);
+        for (const reportNote of data.notes) {
+          lines.push(`    ${reportNote.when} \u2014 ${reportNote.text}`);
         }
         if (story.notes.length > data.notes.length) {
           lines.push(
@@ -482,7 +533,7 @@ function writeStoryReport(stories, options = {}) {
       if (showData) {
         lines.push(`${label("Data")}:`);
         const json = JSON.stringify(data, null, 2);
-        if (colorize) {
+        if (colors) {
           const colored = colorizeJsonSections(json, {
             base: ANSI.grayLight,
             notes: ANSI.grayDark,
@@ -502,11 +553,11 @@ function writeStoryReport(stories, options = {}) {
 0 && (module.exports = {
   ANSI,
   Storyteller,
-  colorizeJsonSections,
   consoleAudience,
-  countBrackets,
   dbAudience,
+  formatDuration,
   formatOrigin,
+  formatStory,
   getLevelColor,
   summarizeStory,
   useStoryteller,