bamtigraph 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,486 @@
+/** Unix seconds, an explicit Date, or an ISO datetime with a timezone offset. */
+type Timestamp = number | Date | string;
+/** RGB or RGBA channels, hexadecimal notation, or a supported named color. */
+type Color = string | readonly [number, number, number] | readonly [number, number, number, number];
+type Values = ArrayLike<number | null | undefined>;
+/** Normalized red, green, blue, and alpha bytes. */
+type RGBA = [number, number, number, number];
+type Interpolation = "linear" | "step-post";
+/** Mutable preprocessing output, with NaN marking missing samples. */
+interface Samples {
+    timestamps: number[];
+    values: number[];
+}
+interface LegendValues {
+    current: number | null;
+    average: number | null;
+    maximum: number | null;
+}
+interface SeriesOptions {
+    kind?: "line" | "area";
+    color?: Color;
+    outline?: Color | null;
+    lineWidth?: number;
+    baseline?: number;
+    interpolation?: Interpolation;
+    gapAfter?: number;
+    legendValues?: Partial<LegendValues> | null;
+}
+interface SeriesInput extends SeriesOptions {
+    name: string;
+    timestamps: ArrayLike<Timestamp>;
+    values: Values;
+}
+interface Series extends Readonly<Required<Omit<SeriesOptions, "legendValues" | "color" | "outline">>> {
+    readonly color: Readonly<RGBA>;
+    readonly outline: Readonly<RGBA> | null;
+    readonly name: string;
+    readonly timestamps: readonly number[];
+    readonly values: readonly number[];
+    readonly legendValues: Readonly<LegendValues> | null;
+}
+interface Tick {
+    time: Timestamp;
+    label: string;
+}
+interface TimeAxis {
+    start?: Timestamp | null;
+    end?: Timestamp | null;
+    mode?: "auto" | "daily" | "weekly" | "monthly" | "yearly" | "custom";
+    timezone?: string;
+    minorSeconds?: number | null;
+    majorSeconds?: number | null;
+    labelSeconds?: number | null;
+    labelFormat?: string | null;
+    labelOffsetSeconds?: number;
+    ticks?: readonly Tick[] | null;
+    minorTicks?: readonly Timestamp[] | null;
+    majorTicks?: readonly Timestamp[] | null;
+}
+interface YAxis {
+    minimum?: number | null;
+    maximum?: number | null;
+    majorStep?: number | null;
+    minorDivisions?: number;
+    base?: 1000 | 1024;
+    scaleFactor?: number | null;
+    suffix?: string | null;
+    decimals?: number | null;
+    legendDecimals?: number;
+    showZeroSuffix?: boolean;
+}
+type ColumnAnchors = readonly [
+    readonly [number, number],
+    readonly [number, number],
+    readonly [number, number]
+];
+interface LegendLayout {
+    nameX?: number;
+    swatchX?: number;
+    swatchWidth?: number;
+    swatchHeight?: number;
+    referenceWidth?: number;
+    autoScaleColumns?: boolean;
+    compact?: ColumnAnchors;
+    expanded?: ColumnAnchors;
+    aligned?: ColumnAnchors;
+}
+interface Layout {
+    width?: number;
+    plotHeight?: number;
+    left?: number;
+    right?: number;
+    top?: number;
+    titleY?: number;
+    titleOffsetX?: number;
+    unitX?: number;
+    xLabelGap?: number;
+    yLabelGap?: number;
+    legendGap?: number;
+    legendRowHeight?: number;
+    legendBottom?: number;
+    legend?: "reference" | "aligned" | "none";
+    legendLayout?: LegendLayout;
+    antialias?: number;
+    pixelScale?: number;
+}
+interface Theme {
+    background?: Color;
+    canvas?: Color;
+    shadeLight?: Color;
+    shadeDark?: Color;
+    text?: Color;
+    minorGrid?: Color;
+    majorGrid?: Color;
+    axis?: Color;
+    arrow?: Color;
+    watermark?: Color;
+    frame?: Color;
+    gridFront?: boolean;
+    gridDash?: readonly [number, number];
+    titleSize?: number;
+    axisSize?: number;
+    unitSize?: number;
+    legendSize?: number;
+    watermarkSize?: number;
+    captionSize?: number;
+    titleAdvance?: number;
+    axisAdvance?: number;
+    legendAdvance?: number;
+}
+interface FontOptions {
+    mode?: "system" | "bitmap";
+    family?: string;
+    titleFamily?: string | null;
+    unitFamily?: string | null;
+    captionFamily?: string | null;
+    strictGlyphs?: boolean;
+}
+interface RuleStyle {
+    color?: Color;
+    width?: number;
+    dash?: readonly [number, number] | null;
+}
+interface HRule extends RuleStyle {
+    value: number;
+}
+interface VRule extends RuleStyle {
+    time: Timestamp;
+}
+/** Immutable chart input. Nested objects merge; arrays replace their defaults. */
+interface ChartOptions {
+    series?: readonly SeriesInput[];
+    title?: string;
+    verticalLabel?: string;
+    watermark?: string;
+    timeAxis?: TimeAxis;
+    yAxis?: YAxis;
+    layout?: Layout;
+    theme?: Theme;
+    fonts?: FontOptions;
+    legendLabels?: readonly [string, string, string];
+    missingLabel?: string;
+    hRules?: readonly HRule[];
+    vRules?: readonly VRule[];
+}
+interface TrafficOptions extends ChartOptions {
+    gapAfter?: number;
+}
+interface Unit {
+    factor: number;
+    suffix: string;
+}
+interface Statistics {
+    name: string;
+    current: number | null;
+    average: number | null;
+    maximum: number | null;
+    minimum: number | null;
+    count: number;
+    missing: number;
+    displayOverride: LegendValues | null;
+}
+/** Serializable chart manifest. Missing statistics are null, not NaN. */
+interface GraphMetadata {
+    version: string;
+    imageSize: [number, number];
+    logicalSize: [number, number];
+    plotBox: [number, number, number, number];
+    pixelScale: number;
+    title: string;
+    verticalLabel: string;
+    watermark: string;
+    timeRange: [number, number];
+    timezone: string;
+    timeMode: string;
+    yRange: [number, number];
+    yStep: number;
+    yUnit: Unit;
+    xLabels: {
+        time: number;
+        label: string;
+        x: number;
+    }[];
+    statistics: Statistics[];
+    statisticsPolicy: string;
+    font: {
+        mode: "system" | "bitmap";
+        family: string | null;
+        pixelAlphabet: string | null;
+    };
+    layout: Layout;
+    theme: Theme;
+    warnings: string[];
+}
+/** Row-major straight-alpha bytes. Pixel storage intentionally remains mutable. */
+interface RGBAImage {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray | Uint8Array;
+}
+interface PNGOptions {
+    metadata?: boolean;
+}
+interface NearestSample {
+    name: string;
+    index: number | null;
+    time: number | null;
+    value: number | null;
+}
+interface MountOptions {
+    interactive?: boolean;
+    ariaLabel?: string;
+    onHover?: (event: {
+        time: number;
+        samples: NearestSample[];
+    }) => void;
+}
+/** Mounted browser lifecycle. Destroy restores the canvas DOM position and attributes. */
+interface Controller {
+    readonly canvas: HTMLCanvasElement;
+    readonly chart: Chart;
+    readonly result: RenderResult;
+    readonly destroyed: boolean;
+    update(patch: ChartOptions | Chart): RenderResult;
+    destroy(): void;
+}
+interface DashboardOptions {
+    gap?: number;
+    padding?: readonly [number, number, number, number];
+    background?: Color;
+    cropHeight?: number | null;
+}
+interface DashboardPanel {
+    chart: Chart;
+    caption?: string;
+}
+interface DashboardMetadata {
+    version: string;
+    imageSize: [number, number];
+    pixelScale: number;
+    panels: {
+        position: [number, number];
+        caption: string;
+        chart: GraphMetadata;
+    }[];
+}
+interface CounterOptions {
+    factor?: number;
+    onDecrease?: "gap" | "wrap";
+    counterBits?: number | null;
+    maxRate?: number | null;
+}
+interface AggregateOptions {
+    interval?: number;
+    method?: "mean" | "min" | "max" | "last" | "sum";
+    origin?: number;
+    minCoverage?: number;
+    expectedStep?: number | null;
+    maxBuckets?: number;
+}
+interface CSVColumn extends SeriesOptions {
+    column: string;
+    name?: string;
+}
+interface CSVOptions {
+    timestampColumn?: string;
+    columns?: readonly CSVColumn[];
+    maxRows?: number;
+    maxBytes?: number;
+}
+interface PixelDifference {
+    pixels: number;
+    exactPixels: number;
+    exactRatio: number;
+    toleranceRatio: number;
+    meanAbsoluteError: number;
+    rootMeanSquareError: number;
+    maxError: number;
+    differenceBox: [number, number, number, number] | null;
+}
+interface CompareOptions {
+    tolerance?: number;
+    box?: readonly [number, number, number, number] | null;
+}
+/** All chart fields after default merging and normalization. */
+interface ResolvedChartOptions extends Omit<Required<ChartOptions>, "series" | "timeAxis" | "yAxis" | "layout" | "theme" | "fonts" | "hRules" | "vRules"> {
+    series: readonly Series[];
+    timeAxis: ResolvedTimeAxis;
+    yAxis: Required<YAxis>;
+    layout: ResolvedLayout;
+    theme: ResolvedTheme;
+    fonts: Required<FontOptions>;
+    hRules: readonly ResolvedHRule[];
+    vRules: readonly ResolvedVRule[];
+}
+/** A calendar axis whose timestamp inputs have been converted to Unix seconds. */
+interface ResolvedTimeAxis extends Omit<Required<TimeAxis>, "start" | "end" | "ticks" | "minorTicks" | "majorTicks"> {
+    start: number | null;
+    end: number | null;
+    ticks: readonly ResolvedTick[] | null;
+    minorTicks: readonly number[] | null;
+    majorTicks: readonly number[] | null;
+}
+/** A label positioned at a numerical Unix timestamp. */
+interface ResolvedTick {
+    time: number;
+    label: string;
+}
+/** Complete logical-pixel layout including the legend geometry. */
+interface ResolvedLayout extends Required<Omit<Layout, "legendLayout">> {
+    legendLayout: Required<LegendLayout>;
+}
+type ThemeColorKey = "background" | "canvas" | "shadeLight" | "shadeDark" | "text" | "minorGrid" | "majorGrid" | "axis" | "arrow" | "watermark" | "frame";
+/** Fully specified theme with parsed RGBA colors. */
+type ResolvedTheme = Required<Omit<Theme, ThemeColorKey>> & {
+    [K in ThemeColorKey]: Readonly<RGBA>;
+};
+/** Normalized horizontal rule in original data units. */
+interface ResolvedHRule {
+    value: number;
+    color: Readonly<RGBA>;
+    width: number;
+    dash: readonly [number, number] | null;
+}
+/** Normalized vertical rule in Unix seconds. */
+interface ResolvedVRule {
+    time: number;
+    color: Readonly<RGBA>;
+    width: number;
+    dash: readonly [number, number] | null;
+}
+/** Recursive readonly view of plain chart configuration and metadata. */
+type DeepReadonly<T> = T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+type Canvas = HTMLCanvasElement | OffscreenCanvas;
+/** BamtiGraph library version. */
+declare const VERSION: string;
+/** Per-operation allocation and enumeration guards. */
+declare const LIMITS: Readonly<{
+    pixels: number;
+    layerPixels: number;
+    ticks: number;
+    series: number;
+    samples: number;
+    text: number;
+}>;
+/** Parse a supported color into integer RGBA bytes. */
+declare function color(value: Color): RGBA;
+/** Normalize a timestamp to Unix seconds; naive dates and invalid calendars fail. */
+declare function epoch(value: Timestamp): number;
+/** Copy, validate, and deeply freeze an independently timestamped series. */
+declare function series(name: string, timestamps: ArrayLike<Timestamp>, values: Values, options?: SeriesOptions): Series;
+/** Create a series with fixed elapsed-second spacing and copied observations. */
+declare function regularSeries(name: string, values: Values, start: Timestamp, step?: number, options?: SeriesOptions): Series;
+/** Daily tick presentation, without resampling observations. */
+declare function daily(options?: TimeAxis | string): TimeAxis;
+/** Weekly calendar-noon labels, without resampling observations. */
+declare function weekly(options?: TimeAxis | string): TimeAxis;
+/** Monthly tick presentation, without resampling observations. */
+declare function monthly(options?: TimeAxis | string): TimeAxis;
+/** Real calendar-month ticks, without resampling observations. */
+declare function yearly(options?: TimeAxis | string): TimeAxis;
+/** Format a value using an already validated common unit and decimal precision. */
+declare function formatValue(value: number | null, unit: Unit, decimals?: number, missingText?: string): string;
+/** Format a timestamp with fixed English calendar names and IANA timezone rules. */
+declare function formatTime(t: Timestamp, zone?: string, format?: string): string;
+/** Encode RGBA pixels as PNG with optional uncompressed UTF-8 chart metadata. */
+declare function encodePNG(image: RGBAImage, metadata?: object | null): Uint8Array<ArrayBuffer>;
+/** Draw image bytes without browser resampling and return the target canvas. */
+declare function drawImageToCanvas(image: RGBAImage, canvas: Canvas): Canvas;
+/** Download bytes in a browser; filenames may not contain path separators. */
+declare function downloadBytes(bytes: Uint8Array, name: string, type?: string): void;
+/** Rendered pixels and a frozen manifest; PNG encoding never requires Canvas. */
+declare class RenderResult<M extends object = GraphMetadata> {
+    /** Pixels intentionally remain mutable; exports observe subsequent edits. */
+    readonly image: RGBAImage;
+    /** Immutable metadata captured at rendering time. */
+    readonly metadata: Readonly<M>;
+    constructor(image: RGBAImage, metadata: M);
+    get width(): number;
+    get height(): number;
+    get data(): RGBAImage["data"];
+    draw(canvas: Canvas): Canvas;
+    toPNG(options?: PNGOptions): Uint8Array<ArrayBuffer>;
+    toBlob(options?: PNGOptions): Blob;
+    download(filename?: string, options?: PNGOptions): void;
+}
+/** An immutable validated chart. Use with() to derive a changed chart. */
+declare class Chart {
+    /** Fully normalized, deeply frozen options used by every render. */
+    readonly config: DeepReadonly<ResolvedChartOptions>;
+    constructor(options?: ChartOptions);
+    with(patch: ChartOptions): Chart;
+    render(): RenderResult;
+    draw(canvas: Canvas): RenderResult;
+    toPNG(options?: PNGOptions): Uint8Array<ArrayBuffer>;
+    mount(canvas: HTMLCanvasElement, options?: MountOptions): Controller;
+    nearest(input: Timestamp): NearestSample[];
+}
+/** Build the conventional inbound area and outbound line without unit conversion. */
+declare function traffic(timestamps: ArrayLike<Timestamp>, inbound: Values, outbound: Values, options?: TrafficOptions): Chart;
+/** Compose native chart renders and optional captions at a shared pixel scale. */
+declare function dashboard(panels: readonly (DashboardPanel | Chart)[], options?: DashboardOptions): RenderResult<DashboardMetadata>;
+/** Compute right-endpoint rates with exact BigInt counter subtraction. */
+declare function counterRate(timestamps: ArrayLike<Timestamp>, counters: ArrayLike<number | bigint | null | undefined>, options?: CounterOptions): Samples;
+/** Aggregate elapsed-time buckets, preserving gaps and explicit coverage policy. */
+declare function aggregate(timestamps: ArrayLike<Timestamp>, values: Values, options?: AggregateOptions): Samples;
+/** Parse quoted CSV into validated series; timestamps must strictly increase. */
+declare function parseCSV(input: string, options?: CSVOptions): Series[];
+/** Export the union of series timestamps, escaping formula-like text headers. */
+declare function toCSV(list: readonly SeriesInput[], options?: {
+    escapeFormulas?: boolean;
+}): string;
+/** Compare RGB pixels without aligning or resizing; alpha is ignored. */
+declare function compareImages(reference: RGBAImage | RenderResult<object>, actual: RGBAImage | RenderResult<object>, options?: CompareOptions): PixelDifference;
+/** Visualize amplified absolute RGB differences in matching images. */
+declare function differenceImage(reference: RGBAImage | RenderResult<object>, actual: RGBAImage | RenderResult<object>, amplify?: number): RenderResult<{
+    imageSize: [number, number];
+    amplify: number;
+}>;
+/** Copy Canvas2D pixels into independently owned RGBA storage. */
+declare function readCanvas(canvas: Canvas): RGBAImage;
+/** Check PNG dimensions and decode with the browser image decoder. */
+declare function decodeImage(blob: Blob): Promise<RGBAImage>;
+/** Return a detached copy of every chart default. */
+declare function defaults(): ChartOptions;
+/** Render a chart once; bitmap mode does not access browser APIs. */
+declare function render(options?: ChartOptions): RenderResult;
+/** Frozen default export, equivalent to the corresponding named exports. */
+interface BamtiGraphAPI {
+    readonly VERSION: typeof VERSION;
+    readonly LIMITS: typeof LIMITS;
+    readonly Chart: typeof Chart;
+    readonly RenderResult: typeof RenderResult;
+    readonly series: typeof series;
+    readonly regularSeries: typeof regularSeries;
+    readonly traffic: typeof traffic;
+    readonly daily: typeof daily;
+    readonly weekly: typeof weekly;
+    readonly monthly: typeof monthly;
+    readonly yearly: typeof yearly;
+    readonly dashboard: typeof dashboard;
+    readonly counterRate: typeof counterRate;
+    readonly aggregate: typeof aggregate;
+    readonly parseCSV: typeof parseCSV;
+    readonly toCSV: typeof toCSV;
+    readonly compareImages: typeof compareImages;
+    readonly differenceImage: typeof differenceImage;
+    readonly encodePNG: typeof encodePNG;
+    readonly decodeImage: typeof decodeImage;
+    readonly readCanvas: typeof readCanvas;
+    readonly drawImageToCanvas: typeof drawImageToCanvas;
+    readonly downloadBytes: typeof downloadBytes;
+    readonly formatTime: typeof formatTime;
+    readonly formatValue: typeof formatValue;
+    readonly epoch: typeof epoch;
+    readonly color: typeof color;
+    readonly defaults: typeof defaults;
+    readonly render: typeof render;
+}
+/** The complete BamtiGraph API; importing this module creates no global. */
+declare const BamtiGraph: Readonly<BamtiGraphAPI>;
+
+export { Chart, LIMITS, RenderResult, VERSION, aggregate, color, compareImages, counterRate, daily, dashboard, decodeImage, BamtiGraph as default, defaults, differenceImage, downloadBytes, drawImageToCanvas, encodePNG, epoch, formatTime, formatValue, monthly, parseCSV, readCanvas, regularSeries, render, series, toCSV, traffic, weekly, yearly };
+export type { AggregateOptions, BamtiGraphAPI, CSVColumn, CSVOptions, ChartOptions, Color, ColumnAnchors, CompareOptions, Controller, CounterOptions, DashboardMetadata, DashboardOptions, DashboardPanel, DeepReadonly, FontOptions, GraphMetadata, HRule, Interpolation, Layout, LegendLayout, LegendValues, MountOptions, NearestSample, PNGOptions, PixelDifference, RGBA, RGBAImage, ResolvedChartOptions, ResolvedHRule, ResolvedLayout, ResolvedTheme, ResolvedTick, ResolvedTimeAxis, ResolvedVRule, RuleStyle, Samples, Series, SeriesInput, SeriesOptions, Statistics, Theme, Tick, TimeAxis, Timestamp, TrafficOptions, Unit, VRule, Values, YAxis };