@lovelaces-io/storyteller 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,15 +1,158 @@
+/**
+ * Which default audience a storyteller registers.
+ *
+ * - `text` — colorized console output for a person watching
+ * - `ndjson` — one JSON object per line for a program reading
+ */
+type OutputFormat = "text" | "ndjson";
+/**
+ * A level written any of the ways people and agents actually write it.
+ * `report("...", { level: "warn" })` should not be a type error.
+ */
+type LevelInput = StoryLevel | "info" | "information" | "warn" | "warning" | "oops" | "error";
+/**
+ * Resolve any accepted level spelling to a stored level label.
+ *
+ * @param input - A level in any accepted spelling
+ * @returns The canonical StoryLevel, defaulting to Information
+ */
+declare function toStoryLevel(input?: LevelInput): StoryLevel;
+/**
+ * Read an environment variable, tolerating runtimes that have no environment at all.
+ *
+ * @param name - Variable name
+ * @returns The trimmed value, or undefined when unset or unavailable
+ */
+declare function readEnvironmentValue(name: string): string | undefined;
+/**
+ * Resolve the minimum level to deliver, from an explicit option then `STORYTELLER_LEVEL`.
+ *
+ * @param requested - Explicit level, if the caller set one
+ * @returns The threshold level, defaulting to Information (deliver everything)
+ */
+declare function resolveMinimumLevel(requested?: StoryLevel | string): StoryLevel;
+/**
+ * Check whether a level clears the configured minimum.
+ *
+ * @param level - The emission's level
+ * @param minimum - The configured threshold
+ */
+declare function meetsLevel(level: StoryLevel, minimum: StoryLevel): boolean;
+/**
+ * Resolve which default audience to register, from an explicit option then
+ * `STORYTELLER_FORMAT`.
+ *
+ * Deliberately not inferred from whether stdout is a TTY: output that silently
+ * changes shape when a process is piped is a debugging afternoon nobody asked for.
+ *
+ * @param requested - Explicit format, if the caller set one
+ * @returns The format, defaulting to text
+ */
+declare function resolveOutputFormat(requested?: OutputFormat): OutputFormat;
+/**
+ * Resolve whether to colorize, from an explicit option then `STORYTELLER_COLOR`.
+ *
+ * @param requested - Explicit choice, if the caller set one
+ * @returns Whether colors should be used, defaulting to true
+ */
+declare function resolveColors(requested?: boolean): boolean;
+
+/** A value that survives JSON.stringify with no loss and no throwing */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type NormalizeOptions = {
+    /** How many levels deep to descend before replacing the value with a truncation marker */
+    maxDepth?: number;
+    /** How many array entries to keep before truncating */
+    maxArrayLength?: number;
+    /** How many object properties to keep before truncating */
+    maxProperties?: number;
+    /** How many characters of a string to keep before truncating */
+    maxStringLength?: number;
+    /** Property names whose values are replaced with the redaction marker */
+    redactKeys?: string[];
+    /** Set false to keep secret-shaped values as-is */
+    redact?: boolean;
+};
+/** Marker written in place of a value that matched a redacted key name */
+declare const REDACTED = "[redacted]";
+/**
+ * Property names whose values are replaced with {@link REDACTED}.
+ * Matching ignores case and separators, so `apiKey`, `api_key` and `API-KEY` all match.
+ */
+declare const DEFAULT_REDACT_KEYS: string[];
+/**
+ * Convert any value into a JSON-safe structure suitable for a story record.
+ *
+ * Handles the shapes real code actually holds — errors, dates, maps, sets, class
+ * instances, binary buffers, circular references, throwing getters — and never throws,
+ * so a hostile object logged by a caller cannot break the delivery pipeline.
+ *
+ * Data dropped for size is replaced with an explicit `@truncated` marker rather than
+ * disappearing silently, so a consumer can tell the difference between "this was empty"
+ * and "this was too big".
+ *
+ * @param input - Any value
+ * @param options - Depth, size and redaction limits
+ * @returns A value that JSON.stringify can always serialize
+ *
+ * @example
+ * ```ts
+ * normalizeValue({ user: new Map([["id", 1]]), apiKey: "sk-live-abc" });
+ * // { user: { "@type": "Map", entries: { id: 1 } }, apiKey: "[redacted]" }
+ * ```
+ */
+declare function normalizeValue(input: unknown, options?: NormalizeOptions): JsonValue;
+/**
+ * Convert an unknown thrown value into a serializable StoryError,
+ * following the `cause` chain and collecting AggregateError members.
+ *
+ * @param rawError - Any thrown or rejected value
+ * @param options - Depth, size and redaction limits applied to attached data
+ * @returns A StoryError safe to store and serialize
+ */
+declare function normalizeError(rawError: unknown, options?: NormalizeOptions): StoryError;
+
 /** Human-readable level labels stored in story records */
 type StoryLevel = "Information" | "Warning" | "Error";
-type StoryContextValue = Record<string, unknown> | string;
+/**
+ * A stored context value. Always JSON-safe — whatever the caller passed in has
+ * already been through the normalizer by the time it reaches a record.
+ */
+type StoryContextValue = JsonValue;
+/** Context accepted from callers. Anything goes; the normalizer makes it storable. */
+type StoryContextInput = unknown;
 type StoryError = {
     name?: string;
     message?: string;
     stack?: string;
-    cause?: unknown;
+    cause?: JsonValue;
+    /** Members of an AggregateError */
+    errors?: StoryError[];
+};
+/** Origin as stored on a record */
+type StoryOrigin = {
+    who?: StoryContextValue;
+    what?: StoryContextValue;
+    where?: StoryContextValue;
+};
+/** Origin as accepted from callers */
+type StoryOriginInput = {
+    who?: StoryContextInput;
+    what?: StoryContextInput;
+    where?: StoryContextInput;
 };
 type StoryNote = {
     timestamp: string;
+    /**
+     * Position within the story, assigned when the note is taken. Gap-free from 0.
+     * Optional so records written before sequencing existed still typecheck.
+     */
+    sequence?: number;
     note: string;
+    /** Omitted when the note carries the story's default Information level */
+    level?: StoryLevel;
     who?: StoryContextValue;
     what?: StoryContextValue;
     where?: StoryContextValue;
@@ -19,13 +162,25 @@ type StoryEventBase = {
     timestamp: string;
     level: StoryLevel;
     title: string;
-    origin?: {
-        who?: StoryContextValue;
-        what?: StoryContextValue;
-        where?: StoryContextValue;
-    };
+    /**
+     * Correlates every note emission with the story it belongs to. Always set on
+     * events this library builds; optional so older stored records still typecheck.
+     */
+    storyId?: string;
+    /**
+     * The story this one is a chapter of. Absent on a top-level story.
+     * Following this field reconstructs the tree of a nested run.
+     */
+    parentStoryId?: string;
+    origin?: StoryOrigin;
     notes: StoryNote[];
     durationMs?: number;
+    /**
+     * How many emissions were dropped for back-pressure while this story was being
+     * collected. Present only when something was actually lost, so the loss shows up
+     * in the record instead of vanishing.
+     */
+    droppedEmissions?: number;
     error?: StoryError;
 };
 type ReportOptions = {
@@ -76,19 +231,125 @@ type FormattedReport = {
 /** @deprecated Use FormattedReport instead */
 type StorySummary = FormattedReport;
 type StoryEvent = StoryEventBase & {
+    kind: "story";
     summarize: (options?: ReportOptions) => FormattedReport;
 };
+/** @deprecated Use StoryEvent — the story-shaped emission */
+type StoryEmission = StoryEvent;
+/** The two things an audience can hear */
+type EmissionKind = "note" | "story";
+/**
+ * A single beat, delivered the moment it happens when narration is live.
+ *
+ * `storyId` and `sequence` are what make streaming lossless: a consumer holding
+ * the beats of a story can order and group them back into the record that
+ * collected narration would have produced.
+ */
+type NoteEmission = StoryNote & {
+    kind: "note";
+    storyId: string;
+    parentStoryId?: string;
+    sequence: number;
+    level: StoryLevel;
+    origin?: StoryOrigin;
+};
+type Emission = NoteEmission | StoryEvent;
 type AudienceMember = {
     name: string;
-    accepts?: (event: StoryEvent) => boolean;
-    hear: (event: StoryEvent) => void | Promise<void>;
+    /**
+     * Which emission kinds this audience wants. Defaults to `["story"]`, so an
+     * audience written before live narration existed keeps hearing only stories.
+     */
+    hears?: EmissionKind[];
+    /**
+     * Declared with method syntax deliberately. TypeScript checks method parameters
+     * bivariantly, so an audience written as `hear: (event: StoryEvent) => void`
+     * still compiles. That would be unsound if such an audience could receive a note
+     * emission — it cannot, because `hears` defaults to stories only.
+     */
+    accepts?(emission: Emission): boolean;
+    hear(emission: Emission): void | Promise<void>;
 };
+/**
+ * How a storyteller narrates.
+ *
+ * - `collected` — beats are buffered and leave as one story record (the default)
+ * - `live` — each beat is emitted as it happens, and the story still lands at the end
+ *
+ * Live narration adds emissions, it never removes them: a consumer that only wants
+ * beats says so with `hears: ["note"]` rather than by silencing the record.
+ */
+type Narration = "collected" | "live";
+/** @deprecated `both` is now the behavior of `live` — beats stream and the story still lands */
+type NarrationInput = Narration | "both";
 type NoteData = {
-    who?: StoryContextValue;
-    what?: StoryContextValue;
-    where?: StoryContextValue;
+    who?: StoryContextInput;
+    what?: StoryContextInput;
+    where?: StoryContextInput;
     error?: unknown;
+    /** Level for this beat alone. Defaults to Information. */
+    level?: LevelInput;
+    /** Emit this beat immediately even when narration is collected */
+    live?: boolean;
+    /** Deliver this beat only to the named audiences */
+    to?: string[];
 };
+type FinishOptions = {
+    /** Defaults to Information */
+    level?: LevelInput;
+    /** The error that ended the story, normalized onto the record */
+    error?: unknown;
+};
+type ChapterOptions = {
+    /** Merged over the parent's origin */
+    origin?: StoryOriginInput;
+    /** Defaults to the parent's setting */
+    narration?: NarrationInput;
+    /** Defaults to the parent's setting */
+    level?: LevelInput;
+    /** Defaults to the parent's handler */
+    onAudienceError?: AudienceErrorHandler;
+    /** Defaults to the parent's bound */
+    maxInFlight?: number;
+};
+type StorytellerOptions = {
+    origin?: StoryOriginInput;
+    audiences?: AudienceMember[];
+    /** Defaults to `STORYTELLER_NARRATION`, then `collected` */
+    narration?: NarrationInput;
+    /**
+     * Which default audience to register: colorized text for a person, NDJSON for a
+     * program. Defaults to `STORYTELLER_FORMAT`, then `text`.
+     */
+    format?: OutputFormat;
+    /**
+     * Share another storyteller's audience registry instead of creating one.
+     * Audiences added to it later reach this storyteller too. When given, no
+     * default audience is registered — the registry already has whatever it has.
+     */
+    audience?: AudienceRegistry;
+    /** The story this one is a chapter of. Set by `chapter()`. */
+    parentStoryId?: string;
+    /**
+     * Drop emissions below this level before they reach any audience.
+     * Defaults to `STORYTELLER_LEVEL`, then Information (deliver everything).
+     */
+    level?: LevelInput;
+    /**
+     * Called when an audience throws or rejects. Without one, a single throttled
+     * warning per audience goes to the console — a logging library that loses
+     * records in silence is worse than one that complains.
+     */
+    onAudienceError?: AudienceErrorHandler;
+    /**
+     * Cap on deliveries in flight to a single audience at once. Live narration is
+     * fire-and-forget, so a slow audience would otherwise grow an unbounded queue.
+     * Past the cap, emissions are dropped and counted on the closing story.
+     */
+    maxInFlight?: number;
+};
+/** Called when an audience member throws or rejects while hearing an emission */
+type AudienceErrorHandler = (error: unknown, member: AudienceMember, emission: Emission) => void;
 /** Manages the set of audience members that receive story events */
 declare class AudienceRegistry {
     private members;
@@ -106,58 +367,148 @@ declare class AudienceRegistry {
     names(): string[];
 }
 /**
- * Collects timestamped notes and emits them as a single structured story event.
+ * Collects timestamped notes and emits them as one structured story — and, when
+ * narration is live, emits each note the moment it is taken.
  *
  * @example
  * ```ts
- * const story = new Storyteller({ origin: { who: "api-server" } });
- * story.note("Request received", { what: { path: "/checkout" } });
- * story.note("Validated cart");
- * story.tell("Checkout started");
+ * const story = new Storyteller({ origin: { who: "api-server" }, narration: "live" });
+ * story.report("Request received", { what: { path: "/checkout" } });
+ * story.report("Validated cart");
+ * story.finish("Checkout started");
  * ```
  */
 declare class Storyteller {
     readonly audience: AudienceRegistry;
     private readonly origin?;
+    private readonly parentStoryId?;
     private notes;
-    constructor(options?: {
-        origin?: StoryEventBase["origin"];
-        audiences?: AudienceMember[];
-    });
+    private narration;
+    private readonly minimumLevel;
+    private readonly onAudienceError;
+    private readonly maxInFlight;
+    /** Deliveries currently awaiting each audience, keyed by audience name */
+    private readonly inFlight;
+    /** Emissions dropped for back-pressure since the current story began */
+    private droppedEmissions;
+    /** Identifies the story currently being collected; regenerated after each telling */
+    private storyId;
+    /** Position of the next note within the current story */
+    private nextSequence;
+    constructor(options?: StorytellerOptions);
+    /**
+     * Switch between collected and live narration at runtime.
+     * Takes effect on the next note; already-buffered notes are not replayed.
+     *
+     * @param narration - `collected` to buffer, `live` to emit each note as it happens
+     * @returns `this` for chaining
+     */
+    narrate(narration: NarrationInput): this;
+    /** The id of the story currently being collected */
+    get currentStoryId(): string;
     /**
-     * Add a timestamped note to the current story.
-     * @param text - What happened
+     * Start a chapter: a child storyteller whose stories are linked back to this
+     * one by `parentStoryId`.
+     *
+     * Real work nests — an agent spawns subtasks, a batch runs per-item operations.
+     * A chapter keeps each of those a complete story in its own right while leaving
+     * the run reconstructable as a tree.
+     *
+     * The child shares this storyteller's audience registry, so audiences added
+     * later reach it too, and inherits narration, level and delivery settings.
+     * Its stories are separate records — a chapter is not folded into the parent's
+     * notes.
+     *
+     * @param options - Origin to merge over the parent's, and any setting to override
+     * @returns A child Storyteller
+     *
+     * @example
+     * ```ts
+     * for (const account of accounts) {
+     *   const chapter = story.chapter({ origin: { what: account.id } });
+     *   chapter.report("Fetching invoices");
+     *   chapter.finish(`Synced ${account.id}`);
+     * }
+     * ```
+     */
+    chapter(options?: ChapterOptions): Storyteller;
+    /**
+     * Report a beat of the current story.
+     *
+     * In collected narration the beat is buffered and leaves with the story. In live
+     * narration it is emitted the moment you call this, so whoever is tuned in sees
+     * the work as it happens.
+     *
+     * Accepts anything, not just a string — pass an error, an API response, a Map, a
+     * class instance — and the value is normalized into a storable shape with the note
+     * text derived from it.
+     *
+     * @param input - What happened: a message, or any value to describe
      * @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" });
+     * story.report("Card charged", { what: { amount: "$42" }, where: "stripe" });
+     * story.report(await response.json());
      * ```
      */
-    note(text: string, data?: NoteData): this;
-    /** Clear all accumulated notes without emitting a story */
+    report(input: unknown, data?: NoteData): this;
+    /** Clear all accumulated notes without emitting a story, and start a new story id */
     reset(): this;
     /** Preview the current notes as a formatted report without emitting or clearing them */
     summarize(options?: PreviewOptions): FormattedReport;
-    /** Tell a success story — everything went well */
+    /**
+     * Finish the story: emit everything collected so far as one record, and start fresh.
+     *
+     * @param title - What the story was about
+     * @param options - Level, and the error that ended it
+     * @returns A one-shot handle whose `.to()` overrides the audience list — call it
+     *   synchronously, delivery happens on the next microtask
+     *
+     * @example
+     * ```ts
+     * story.finish("Sync complete");
+     * story.finish("Sync failed", { level: "oops", error }).to("db");
+     * ```
+     */
+    finish(title: string, options?: FinishOptions): {
+        to: (...names: string[]) => void;
+    };
+    /** @deprecated Use `finish(title)`. Removed at 1.0. */
     tell(title: string): {
         to: (...names: string[]) => void;
     };
-    /** Tell a cautionary story — something was off but it's handled */
+    /** @deprecated Use `finish(title, { level: "warn" })`. Removed at 1.0. */
     warn(title: string): {
         to: (...names: string[]) => void;
     };
-    /** Tell an error story — something broke. Pass the error for automatic normalization. */
+    /** @deprecated Use `finish(title, { level: "oops", error })`. Removed at 1.0. */
     oops(title: string, error?: unknown): {
         to: (...names: string[]) => void;
     };
+    /** @deprecated Use `report()`. Removed at 1.0. */
+    note(input: unknown, data?: NoteData): this;
+    /** Emit a single note to the audiences listening for notes */
+    private emitNote;
     /** Build a story event and schedule delivery, returning a handle to override the audience list */
     private createDelivery;
-    /** Assemble the story event from current notes and clear notes for the next story */
+    /** Assemble the story event from current notes and start a fresh story */
     private buildEvent;
-    /** Deliver a story event to matching audience members */
+    /** Begin a new story: fresh id, sequence back to zero */
+    private startNewStory;
+    /** Deliver an emission to the audience members listening for its kind */
     private deliver;
+    /** Run an audience's accepts() without letting a throw from it lose the emission */
+    private acceptsSafely;
+    /**
+     * Hand an emission to one audience, keeping its failures and its slowness
+     * contained: a throw is reported rather than swallowed, and a backlog is dropped
+     * rather than grown without limit.
+     */
+    private hearSafely;
+    /** Report an audience failure without ever letting it reach caller code */
+    private handleAudienceError;
 }
 
 /**
@@ -180,7 +531,8 @@ declare function formatDuration(milliseconds: number): string;
 declare const summarizeStory: typeof formatStory;
 
 type StorytellerSharedOptions = {
-    origin?: StoryEventBase["origin"];
+    origin?: StoryOriginInput;
+    narration?: NarrationInput;
     reset?: boolean;
 };
 /**
@@ -198,9 +550,19 @@ type StorytellerSharedOptions = {
  */
 declare function useStoryteller(options?: StorytellerSharedOptions): Storyteller;
 
+type ConsoleAudienceOptions = {
+    /** Set false to strip ANSI colors from live note lines. Defaults to `STORYTELLER_COLOR`. */
+    colors?: boolean;
+};
 /**
- * Create an audience that prints stories to the console with color-coded grouped output.
- * Registered by default on every Storyteller instance.
+ * Create an audience that prints to the console: one compact line per note when
+ * narration is live, and a color-coded grouped record when a story is told.
+ *
+ * Registered by default on every Storyteller instance. It listens for notes as well
+ * as stories, so switching a storyteller to live narration shows something immediately
+ * without registering anything extra.
+ *
+ * @param options - Rendering options for live note lines
  *
  * @example
  * ```ts
@@ -208,12 +570,15 @@ declare function useStoryteller(options?: StorytellerSharedOptions): Storyteller
  * story.audience.add(consoleAudience());
  * ```
  */
-declare function consoleAudience(): AudienceMember;
+declare function consoleAudience(options?: ConsoleAudienceOptions): AudienceMember;
 
 /**
  * Create an audience that stores warn and oops stories via your insert function.
  * Tell-level events are filtered out to reduce noise — only warnings and errors are persisted.
  *
+ * Hears stories only. Live notes are not persisted: the story record already contains
+ * every note, so storing both would double-write the same content.
+ *
  * Note: if the insert function throws, the error is silently caught by the delivery
  * pipeline (Promise.allSettled). Wrap your insert with try/catch to handle failures.
  *
@@ -230,6 +595,36 @@ declare function consoleAudience(): AudienceMember;
  */
 declare function dbAudience(insert: (event: StoryEvent) => Promise<void> | void): AudienceMember;
 
+/** Anything that can take a line of text — a Node stream, or your own sink */
+type LineWriter = {
+    write: (chunk: string) => unknown;
+};
+type NdjsonAudienceOptions = {
+    /** Where lines go. Defaults to stdout in Node, console.log elsewhere. */
+    stream?: LineWriter;
+    /** Register under a different name, e.g. to run two streams at once */
+    name?: string;
+    /** Minimum level to write. Defaults to `STORYTELLER_LEVEL`, then everything. */
+    level?: StoryLevel;
+};
+/**
+ * Create an audience that writes one JSON object per line — every note and every
+ * story, nothing else on the channel.
+ *
+ * This is the format to give a program: a log shipper, `jq`, or an agent reading
+ * another process's output. Each line parses on its own, and `storyId` plus
+ * `sequence` let a reader group streamed notes back into their story.
+ *
+ * @param options - Stream, name and level threshold
+ *
+ * @example
+ * ```ts
+ * story.audience.remove("console");
+ * story.audience.add(ndjsonAudience({ stream: process.stderr }));
+ * ```
+ */
+declare function ndjsonAudience(options?: NdjsonAudienceOptions): AudienceMember;
+
 type StoryReportOptions = {
     timezone?: string;
     locale?: string;
@@ -253,6 +648,20 @@ declare const ANSI: {
 /** Map a story level to its corresponding ANSI terminal color */
 declare function getLevelColor(level: StoryLevel): string;
 /** Format an origin context into a human-readable path like "app / page / component" */
-declare function formatOrigin(origin?: StoryEventBase["origin"]): string | undefined;
+declare function formatOrigin(origin?: StoryOrigin): string | undefined;
+/**
+ * Condense a note's context into a short inline summary for one-line output.
+ * The full values are always available on the story record and the NDJSON stream,
+ * so this can afford to be lossy in favor of staying readable.
+ *
+ * @param note - The note's context fields
+ * @returns A brace-wrapped summary, or undefined when there is no context
+ */
+declare function summarizeContext(note: {
+    note?: string;
+    what?: JsonValue;
+    where?: JsonValue;
+    error?: StoryError;
+}): string | undefined;
 
-export { ANSI, type AudienceMember, type FormattedReport, type PreviewOptions, type ReportNote, type ReportOptions, type StoryContextValue, type StoryError, type StoryEvent, type StoryEventBase, type StoryLevel, type StoryNote, type StoryPreviewOptions, type StoryReport, type StoryReportOptions, type StorySummary, type StorySummaryData, type StorySummaryNote, type StorySummaryOptions, Storyteller, consoleAudience, dbAudience, formatDuration, formatOrigin, formatStory, getLevelColor, summarizeStory, useStoryteller, writeStoryReport };
+export { ANSI, type AudienceErrorHandler, type AudienceMember, AudienceRegistry, type ChapterOptions, type ConsoleAudienceOptions, DEFAULT_REDACT_KEYS, type Emission, type EmissionKind, type FinishOptions, type FormattedReport, type JsonValue, type LevelInput, type LineWriter, type Narration, type NarrationInput, type NdjsonAudienceOptions, type NormalizeOptions, type NoteData, type NoteEmission, type OutputFormat, type PreviewOptions, REDACTED, type ReportNote, type ReportOptions, type StoryContextInput, type StoryContextValue, type StoryEmission, type StoryError, type StoryEvent, type StoryEventBase, type StoryLevel, type StoryNote, type StoryOrigin, type StoryOriginInput, type StoryPreviewOptions, type StoryReport, type StoryReportOptions, type StorySummary, type StorySummaryData, type StorySummaryNote, type StorySummaryOptions, Storyteller, type StorytellerOptions, consoleAudience, dbAudience, formatDuration, formatOrigin, formatStory, getLevelColor, meetsLevel, ndjsonAudience, normalizeError, normalizeValue, readEnvironmentValue, resolveColors, resolveMinimumLevel, resolveOutputFormat, summarizeContext, summarizeStory, toStoryLevel, useStoryteller, writeStoryReport };