Metrics API for Bun and Node

type SeriesKind = 'gauge' | 'counter' | 'histogram'

type Labels = Record<string, string>

type Condition = LabelValue | readonly LabelValue[] | {
    not: LabelValue | readonly LabelValue[]
} | {
    prefix: string
}

interface Query {
    /** the series of this name; a timer's name, the series it writes */
    name?: string | undefined
    where?: Record<string, Condition> | undefined
    /** the span before now the range covers; or from and to */
    since?: Duration | undefined
    /** the range's start, included */
    from?: Time | undefined
    /** the range's end, excluded; now, a sample taken now in the range, unless given */
    to?: Time | undefined
}

interface SeriesInput {
    name: string
    kind: SeriesKind
    labels?: Record<string, LabelValue>
    samples?: readonly (readonly [time: Time, value: number])[]
    times?: readonly Time[] | Float64Array
    values?: readonly number[] | Float64Array
    /** how long the name's samples stay: its own, kept in the file; unless given, what it keeps already */
    keep?: Duration | undefined
}

interface Series {
    name: string
    kind: SeriesKind
    labels: Labels
    /** unix milliseconds, in the order of their times */
    times: Float64Array
    /** the values, whose bytes keep each one's bits: -0 and a NaN's payload survive */
    values: Float64Array
}

type Percentile = 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'p99.9' | (`p${number}` & Record<never, never>)

type Op = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'increase' | 'rate' | 'delta' | 'first' | 'last' | Percentile

interface AggregateQuery<O extends Op = Op> extends Query {
    /** the buckets' span, counted from 1970 in UTC; the range is one bucket without it */
    every?: Duration | undefined
    op: O
    /** the labels a group keeps; without by and without, every series of a name is one group */
    by?: readonly string[] | undefined
    /** the labels a group leaves out, keeping every other; [] keeps every series apart */
    without?: readonly string[] | undefined
    /** a timer's percentile also gives a point between its bounds, interpolated: an estimate */
    estimate?: boolean | undefined
}

interface ValueBucket extends Spanned {
    value: number
}

interface PercentileBucket extends Spanned {
    value?: number
    lower?: number
    /** Infinity past the last bound */
    upper?: number
    estimate?: number
}

type Bucket<O extends Op = Op> = O extends Percentile ? PercentileBucket : ValueBucket

interface Aggregate<O extends Op = Op> {
    name: string
    /** the labels by kept or without left */
    labels: Labels
    /** a bucket without samples is left out */
    buckets: Bucket<O>[]
}

interface Newest {
    name: string
    labels: Labels
    at: Date
    value: number
}

interface Plan {
    series: number
    bytes: number
    decoded: number
    exceeds: {
        limit: string
        wanted: number
        bound: number
    } | undefined
}

interface PageOptions {
    prefix?: string | undefined
    /** 1000 unless given, 10,000 at most */
    limit?: number | undefined
    /** a page's next, so that a page's options can be the one before's */
    after?: string | undefined
}

interface NameInfo {
    name: string
    kind: SeriesKind
    seriesCount: number
    unit: string
    help: string
    keep: DurationText
    /** its oldest sample, or where its keep begins while it holds samples from before */
    retainedFrom: Date
    newest: Date
}

interface NamePage {
    names: NameInfo[]
    /** where the next page starts; none on the last */
    next?: string
}

interface LabelPage {
    labels: string[]
    next?: string
}

interface ValuePage {
    values: string[]
    next?: string
}

interface Description {
    unit?: string
    help?: string
}

interface Damage {
    name: string
    labels: Labels
    error: string
}

class Metrics {}

ingest(series: SeriesInput | readonly SeriesInput[]): Promise<void>

read(query: Query): Promise<Series[]>

latest(query: Query): Promise<Newest[]>

aggregate<O extends Op>(query: AggregateQuery<O>): Promise<Aggregate<O>[]>

explain(query: Query & Partial<Omit<AggregateQuery, keyof Query>>): Promise<Plan>

names(options?: PageOptions): Promise<NamePage>

labelNames(name: string, options?: PageOptions): Promise<LabelPage>

labelValues(name: string, label: string, options?: PageOptions): Promise<ValuePage>

describe(name: string, description: Description): Promise<void>

description(name: string): Promise<{
        unit: string
        help: string
    }>

delete(series: {
        name: string
        labels: Record<string, LabelValue>
    }): Promise<boolean>

damaged(): Promise<Damage[]>

for (let damaged = await store.metrics.damaged(); damaged.length > 0; damaged = await store.metrics.damaged()) {
    for (const series of damaged) await store.metrics.delete(series)
}

flush(): Promise<void>

counter<L extends string = string>(name: string, options?: InstrumentOptions): Counter<L>

gauge<L extends string = string>(name: string, options?: InstrumentOptions): Gauge<L>

gaugeFunc(name: string, read: () => number | Promise<number>, options?: GaugeFuncOptions): void

store.metrics.gaugeFunc('queue_depth', () => emails.depth(), { labels: { queue: 'emails' } })

timer<L extends string = string>(name: string, options?: TimerOptions): Timer<L>

histogram<L extends string = string>(name: string, options?: HistogramOptions): Histogram<L>

type LabelValue = string | number | boolean

interface InstrumentOptions {
    /** the unit of its values, 32 bytes at most: 'bytes', '%' */
    unit?: string | undefined
    /** a line on what it means, 1024 bytes at most */
    help?: string | undefined
    /** how long its name's samples stay, as ingest takes it */
    keep?: Duration | undefined
}

type Buckets = readonly number[] | 'exponential'

interface TimerOptions {
    help?: string | undefined
    keep?: Duration | undefined
    /** the upper bounds of its spread, to which the store adds +Inf, or 'exponential' */
    buckets?: Buckets | undefined
}

interface HistogramOptions extends InstrumentOptions {
    buckets?: Buckets | undefined
}

interface GaugeFuncOptions extends InstrumentOptions {
    /** the set of labels its function reads; another set of the name takes a function of its own */
    labels?: InstrumentLabels | undefined
}

type InstrumentLabels<L extends string = string> = {
    readonly [K in L]?: LabelValue
}

class Instruments {}

declare(name: string, form: Form, options: HistogramOptions, read?: boolean): Declared

reader(name: string, labels: Record<string, string>, options: InstrumentOptions, read: () => unknown): void

setOf(instrument: Declared, labels: Record<string, string>): LabelSet

pending(set: LabelSet): Change | undefined

change(set: LabelSet): Change

flush(): Promise<boolean>

stop(): Promise<void>

class Counter<L extends string = string> {}

with(labels: InstrumentLabels<L>): Counter<L>

inc(): void

add(n: number): void

class Gauge<L extends string = string> {}

with(labels: InstrumentLabels<L>): Gauge<L>

set(value: number): void

add(n: number): void

inc(): void

dec(): void

class Timer<L extends string = string> {}

with(labels: InstrumentLabels<L>): Timer<L>

record(duration: Duration): void

measure<R>(fn: () => R | Promise<R>): Promise<R>

const user = await latency.with({ route: '/users' }).measure(() => users.get(id))

start(): Timing

class Timing {}

stop(): number

class Histogram<L extends string = string> {}

with(labels: InstrumentLabels<L>): Histogram<L>

record(value: number): void

function exponentialBuckets(start: number, factor: number, count: number): number[]