@code-pushup/utils 0.109.0 → 0.111.0

package/src/lib/profiler/profiler.d.ts

@@ -1,5 +1,11 @@
+import { type PerformanceObserverOptions } from '../performance-observer.js';
 import { type ActionTrackConfigs, type MeasureCtxOptions, type MeasureOptions } from '../user-timing-extensibility-api-utils.js';
 import type { ActionTrackEntryPayload, DevToolsColor, EntryMeta } from '../user-timing-extensibility-api.type.js';
+import type { AppendableSink } from '../wal.js';
+/**
+ * Generates a unique profiler ID based on performance time origin, process ID, thread ID, and instance count.
+ */
+export declare function getProfilerId(): string;
 /**
  * Configuration options for creating a Profiler instance.
  *
@@ -41,6 +47,8 @@ export type ProfilerOptions<T extends ActionTrackConfigs = ActionTrackConfigs> =
  */
 export declare class Profiler<T extends ActionTrackConfigs> {
     #private;
+    static instanceCount: number;
+    readonly id: string;
     readonly tracks: Record<keyof T, ActionTrackEntryPayload> | undefined;
     /**
      * Creates a new Profiler instance with the specified configuration.
@@ -131,4 +139,84 @@ export declare class Profiler<T extends ActionTrackConfigs> {
      */
     measureAsync<R>(event: string, work: () => Promise<R>, options?: MeasureOptions<R>): Promise<R>;
 }
+/**
+ * Options for configuring a NodejsProfiler instance.
+ *
+ * Extends ProfilerOptions with a required sink parameter.
+ *
+ * @template Tracks - Record type defining available track names and their configurations
+ */
+export type NodejsProfilerOptions<DomainEvents, Tracks extends Record<string, ActionTrackEntryPayload>> = ProfilerOptions<Tracks> & Omit<PerformanceObserverOptions<DomainEvents>, 'sink'> & {
+    /**
+     * Sink for buffering and flushing performance data
+     */
+    sink: AppendableSink<DomainEvents>;
+    /**
+     * Name of the environment variable to check for debug mode.
+     * When the env var is set to 'true', profiler state transitions create performance marks for debugging.
+     *
+     * @default 'CP_PROFILER_DEBUG'
+     */
+    debugEnvVar?: string;
+};
+/**
+ * Performance profiler with automatic process exit handling for buffered performance data.
+ *
+ * This class extends the base {@link Profiler} with automatic flushing of performance data
+ * when the process exits. It accepts a {@link PerformanceObserverSink} that buffers performance
+ * entries and ensures they are written out during process termination, even for unexpected exits.
+ *
+ * The sink defines the output format for performance data, enabling flexible serialization
+ * to various formats such as DevTools TraceEvent JSON, OpenTelemetry protocol buffers,
+ * or custom domain-specific formats.
+ *
+ * The profiler automatically subscribes to the performance observer when enabled and installs
+ * exit handlers that flush buffered data on process termination (signals, fatal errors, or normal exit).
+ *
+ */
+export declare class NodejsProfiler<DomainEvents, Tracks extends Record<string, ActionTrackEntryPayload> = Record<string, ActionTrackEntryPayload>> extends Profiler<Tracks> {
+    #private;
+    /**
+     * Creates a NodejsProfiler instance.
+     * @param options - Configuration with required sink
+     */
+    constructor(options: NodejsProfilerOptions<DomainEvents, Tracks>);
+    /**
+     * Returns whether debug mode is enabled for profiler state transitions.
+     *
+     * Debug mode is determined by the environment variable specified by `debugEnvVar`
+     * (defaults to 'CP_PROFILER_DEBUG'). When enabled, profiler state transitions create
+     * performance marks for debugging.
+     *
+     * @returns true if debug mode is enabled, false otherwise
+     */
+    get debug(): boolean;
+    /**
+     * Closes profiler and releases resources. Idempotent, safe for exit handlers.
+     * **Exit Handler Usage**: Call only this method from process exit handlers.
+     */
+    close(): void;
+    /** @returns Current profiler state */
+    get state(): 'idle' | 'running' | 'closed';
+    /** @returns Whether profiler is in 'running' state */
+    isEnabled(): boolean;
+    /** Enables profiling (start/stop) */
+    setEnabled(enabled: boolean): void;
+    /** @returns Queue statistics and profiling state for monitoring */
+    get stats(): {
+        debug: boolean;
+        state: "idle" | "running" | "closed";
+        walOpen: boolean;
+        isSubscribed: boolean;
+        queued: number;
+        dropped: number;
+        written: number;
+        maxQueueSize: number;
+        flushThreshold: number;
+        addedSinceLastFlush: number;
+        buffered: boolean;
+    };
+    /** Flushes buffered performance data to sink. */
+    flush(): void;
+}
 export {};

package/src/lib/profiler/profiler.js

@@ -1,7 +1,18 @@
+import { performance } from 'node:perf_hooks';
 import process from 'node:process';
+import { threadId } from 'node:worker_threads';
 import { isEnvVarEnabled } from '../env.js';
+import { PerformanceObserverSink, } from '../performance-observer.js';
+import { objectToEntries } from '../transform.js';
 import { asOptions, markerPayload, measureCtx, setupTracks, } from '../user-timing-extensibility-api-utils.js';
-import { PROFILER_ENABLED_ENV_VAR } from './constants.js';
+import { PROFILER_DEBUG_ENV_VAR, PROFILER_ENABLED_ENV_VAR, } from './constants.js';
+/**
+ * Generates a unique profiler ID based on performance time origin, process ID, thread ID, and instance count.
+ */
+export function getProfilerId() {
+    // eslint-disable-next-line functional/immutable-data
+    return `${Math.round(performance.timeOrigin)}.${process.pid}.${threadId}.${++Profiler.instanceCount}`;
+}
 /**
  * Performance profiler that creates structured timing measurements with Chrome DevTools Extensibility API payloads.
  *
@@ -10,7 +21,9 @@ import { PROFILER_ENABLED_ENV_VAR } from './constants.js';
  *
  */
 export class Profiler {
-    #enabled;
+    static instanceCount = 0;
+    id = getProfilerId();
+    #enabled = false;
     #defaults;
     tracks;
     #ctxOf;
@@ -86,7 +99,7 @@ export class Profiler {
      * });
      */
     marker(name, opt) {
-        if (!this.#enabled) {
+        if (!this.isEnabled()) {
             return;
         }
         performance.mark(name, asOptions(markerPayload({
@@ -112,7 +125,7 @@ export class Profiler {
      *
      */
     measure(event, work, options) {
-        if (!this.#enabled) {
+        if (!this.isEnabled()) {
             return work();
         }
         const { start, success, error } = this.#ctxOf(event, options);
@@ -144,7 +157,7 @@ export class Profiler {
      *
      */
     async measureAsync(event, work, options) {
-        if (!this.#enabled) {
+        if (!this.isEnabled()) {
             return await work();
         }
         const { start, success, error } = this.#ctxOf(event, options);
@@ -160,4 +173,143 @@ export class Profiler {
         }
     }
 }
+/**
+ * Performance profiler with automatic process exit handling for buffered performance data.
+ *
+ * This class extends the base {@link Profiler} with automatic flushing of performance data
+ * when the process exits. It accepts a {@link PerformanceObserverSink} that buffers performance
+ * entries and ensures they are written out during process termination, even for unexpected exits.
+ *
+ * The sink defines the output format for performance data, enabling flexible serialization
+ * to various formats such as DevTools TraceEvent JSON, OpenTelemetry protocol buffers,
+ * or custom domain-specific formats.
+ *
+ * The profiler automatically subscribes to the performance observer when enabled and installs
+ * exit handlers that flush buffered data on process termination (signals, fatal errors, or normal exit).
+ *
+ */
+export class NodejsProfiler extends Profiler {
+    #sink;
+    #performanceObserverSink;
+    #state = 'idle';
+    #debug;
+    /**
+     * Creates a NodejsProfiler instance.
+     * @param options - Configuration with required sink
+     */
+    constructor(options) {
+        const { sink, encodePerfEntry, captureBufferedEntries, flushThreshold, maxQueueSize, enabled, debugEnvVar = PROFILER_DEBUG_ENV_VAR, ...profilerOptions } = options;
+        const initialEnabled = enabled ?? isEnvVarEnabled(PROFILER_ENABLED_ENV_VAR);
+        super({ ...profilerOptions, enabled: initialEnabled });
+        this.#sink = sink;
+        this.#debug = isEnvVarEnabled(debugEnvVar);
+        this.#performanceObserverSink = new PerformanceObserverSink({
+            sink,
+            encodePerfEntry,
+            captureBufferedEntries,
+            flushThreshold,
+            maxQueueSize,
+            debugEnvVar,
+        });
+        if (initialEnabled) {
+            this.#transition('running');
+        }
+    }
+    /**
+     * Returns whether debug mode is enabled for profiler state transitions.
+     *
+     * Debug mode is determined by the environment variable specified by `debugEnvVar`
+     * (defaults to 'CP_PROFILER_DEBUG'). When enabled, profiler state transitions create
+     * performance marks for debugging.
+     *
+     * @returns true if debug mode is enabled, false otherwise
+     */
+    get debug() {
+        return this.#debug;
+    }
+    /**
+     * Creates a performance marker for a profiler state transition.
+     * @param transition - The state transition that occurred
+     */
+    #transitionMarker(transition) {
+        const transitionMarkerPayload = {
+            dataType: 'marker',
+            color: 'primary',
+            tooltipText: `Profiler state transition: ${transition}`,
+            properties: [['Transition', transition], ...objectToEntries(this.stats)],
+        };
+        this.marker(transition, transitionMarkerPayload);
+    }
+    #transition(next) {
+        if (this.#state === next) {
+            return;
+        }
+        if (this.#state === 'closed') {
+            throw new Error('Profiler already closed');
+        }
+        const transition = `${this.#state}->${next}`;
+        switch (transition) {
+            case 'idle->running':
+                super.setEnabled(true);
+                this.#sink.open?.();
+                this.#performanceObserverSink.subscribe();
+                break;
+            case 'running->idle':
+            case 'running->closed':
+                super.setEnabled(false);
+                this.#performanceObserverSink.unsubscribe();
+                this.#sink.close?.();
+                break;
+            case 'idle->closed':
+                // No-op, was not open
+                break;
+            default:
+                throw new Error(`Invalid transition: ${this.#state} -> ${next}`);
+        }
+        this.#state = next;
+        if (this.#debug) {
+            this.#transitionMarker(transition);
+        }
+    }
+    /**
+     * Closes profiler and releases resources. Idempotent, safe for exit handlers.
+     * **Exit Handler Usage**: Call only this method from process exit handlers.
+     */
+    close() {
+        this.#transition('closed');
+    }
+    /** @returns Current profiler state */
+    get state() {
+        return this.#state;
+    }
+    /** @returns Whether profiler is in 'running' state */
+    isEnabled() {
+        return this.#state === 'running';
+    }
+    /** Enables profiling (start/stop) */
+    setEnabled(enabled) {
+        if (enabled) {
+            this.#transition('running');
+        }
+        else {
+            this.#transition('idle');
+        }
+    }
+    /** @returns Queue statistics and profiling state for monitoring */
+    get stats() {
+        return {
+            ...this.#performanceObserverSink.getStats(),
+            debug: this.#debug,
+            state: this.#state,
+            walOpen: !this.#sink.isClosed(),
+        };
+    }
+    /** Flushes buffered performance data to sink. */
+    flush() {
+        if (this.#state === 'closed') {
+            return; // No-op if closed
+        }
+        this.#performanceObserverSink.flush();
+    }
+}
 //# sourceMappingURL=profiler.js.map

package/src/lib/profiler/profiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"profiler.js","sourceRoot":"","sources":["../../../../src/lib/profiler/profiler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"profiler.js","sourceRoot":"","sources":["../../../../src/lib/profiler/profiler.ts"],"names":[],"mappings":"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"}

package/src/lib/{trace-file-utils.d.ts → profiler/trace-file-utils.d.ts}

@@ -1,5 +1,6 @@
-import type { PerformanceMark, PerformanceMeasure } from 'node:perf_hooks';
-import type { BeginEvent, CompleteEvent, EndEvent, InstantEvent, InstantEventArgs, InstantEventTracingStartedInBrowser, SpanEventArgs, TraceEvent, TraceEventContainer } from './trace-file.type.js';
+import type { PerformanceEntry, PerformanceMark, PerformanceMeasure } from 'node:perf_hooks';
+import type { UserTimingDetail } from '../user-timing-extensibility-api.type.js';
+import type { BeginEvent, CompleteEvent, EndEvent, InstantEvent, InstantEventArgs, InstantEventTracingStartedInBrowser, SpanEventArgs, TraceEvent, TraceEventContainer, TraceEventRaw, TraceMetadata, UserTimingTraceEvent } from './trace-file.type.js';
 /**
  * Generates a unique ID for linking begin and end span events in Chrome traces.
  * @returns Object with local ID string for the id2 field
@@ -121,6 +122,26 @@ export declare const measureToSpanEvents: (entry: PerformanceMeasure, opt?: {
     pid?: number;
     tid?: number;
 }) => [BeginEvent, EndEvent];
+/**
+ * Converts a PerformanceEntry to an array of UserTimingTraceEvents.
+ * A mark is converted to an instant event, and a measure is converted to a pair of span events.
+ * Other entry types are ignored.
+ * @param entry - Performance entry
+ * @returns UserTimingTraceEvent[]
+ */
+export declare function entryToTraceEvents(entry: PerformanceEntry): UserTimingTraceEvent[];
+/**
+ * Creates trace metadata object with standard DevTools fields and custom metadata.
+ * @param startDate - Optional start date for the trace, defaults to current date
+ * @param metadata - Optional additional metadata to merge into the trace metadata
+ * @returns TraceMetadata object with source, startTime, and merged custom metadata
+ */
+export declare function getTraceMetadata(startDate?: Date, metadata?: Record<string, unknown>): {
+    source: string;
+    startTime: string;
+    hardwareConcurrency: number;
+    dataOrigin: string;
+};
 /**
  * Creates a complete trace file container with metadata.
  * @param opt - Trace file configuration
@@ -129,5 +150,34 @@ export declare const measureToSpanEvents: (entry: PerformanceMeasure, opt?: {
 export declare const getTraceFile: (opt: {
     traceEvents: TraceEvent[];
     startTime?: string;
+    metadata?: Partial<TraceMetadata>;
 }) => TraceEventContainer;
+/**
+ * Decodes a JSON string detail property back to its original object form.
+ * @param target - Object containing a detail property as a JSON string
+ * @returns UserTimingDetail with the detail property parsed from JSON
+ */
+export declare function decodeDetail(target: {
+    detail: string;
+}): UserTimingDetail;
+/**
+ * Encodes object detail properties to JSON strings for storage/transmission.
+ * @param target - UserTimingDetail object with detail property to encode
+ * @returns UserTimingDetail with object details converted to JSON strings
+ */
+export declare function encodeDetail(target: UserTimingDetail): UserTimingDetail;
+/**
+ * Decodes a raw trace event with JSON string details back to typed UserTimingTraceEvent.
+ * Parses detail properties from JSON strings to objects.
+ * @param event - Raw trace event with string-encoded details
+ * @returns UserTimingTraceEvent with parsed detail objects
+ */
+export declare function decodeTraceEvent({ args, ...rest }: TraceEventRaw): UserTimingTraceEvent;
+/**
+ * Encodes a UserTimingTraceEvent to raw format with JSON string details.
+ * Converts object details to JSON strings for storage/transmission.
+ * @param event - UserTimingTraceEvent with object details
+ * @returns TraceEventRaw with string-encoded details
+ */
+export declare function encodeTraceEvent({ args, ...rest }: UserTimingTraceEvent): TraceEventRaw;
 export {};

package/src/lib/{trace-file-utils.js → profiler/trace-file-utils.js}

@@ -1,6 +1,5 @@
-import os from 'node:os';
 import { threadId } from 'node:worker_threads';
-import { defaultClock } from './clock-epoch.js';
+import { defaultClock } from '../clock-epoch.js';
 /** Global counter for generating unique span IDs within a trace */
 // eslint-disable-next-line functional/no-let
 let id2Count = 0;
@@ -11,8 +10,11 @@ let id2Count = 0;
 export const nextId2 = () => ({ local: `0x${++id2Count}` });
 /**
  * Provides default values for trace event properties.
- * @param opt - Optional overrides for pid, tid, and timestamp
- * @returns Object with pid, tid, and timestamp
+ * @param opt - Optional overrides for process ID, thread ID, and timestamp
+ * @param opt.pid - Process ID override, defaults to current process PID
+ * @param opt.tid - Thread ID override, defaults to current thread ID
+ * @param opt.ts - Timestamp override in microseconds, defaults to current epoch time
+ * @returns Object containing pid, tid, and ts with defaults applied
  */
 const defaults = (opt) => ({
     pid: opt?.pid ?? process.pid,
@@ -162,6 +164,37 @@ export const measureToSpanEvents = (entry, opt) => getSpan({
     tsE: defaultClock.fromEntry(entry, true),
     args: entry.detail ? { data: { detail: entry.detail } } : undefined,
 });
+/**
+ * Converts a PerformanceEntry to an array of UserTimingTraceEvents.
+ * A mark is converted to an instant event, and a measure is converted to a pair of span events.
+ * Other entry types are ignored.
+ * @param entry - Performance entry
+ * @returns UserTimingTraceEvent[]
+ */
+export function entryToTraceEvents(entry) {
+    if (entry.entryType === 'mark') {
+        return [markToInstantEvent(entry)];
+    }
+    if (entry.entryType === 'measure') {
+        return measureToSpanEvents(entry);
+    }
+    return [];
+}
+/**
+ * Creates trace metadata object with standard DevTools fields and custom metadata.
+ * @param startDate - Optional start date for the trace, defaults to current date
+ * @param metadata - Optional additional metadata to merge into the trace metadata
+ * @returns TraceMetadata object with source, startTime, and merged custom metadata
+ */
+export function getTraceMetadata(startDate, metadata) {
+    return {
+        source: 'DevTools',
+        startTime: startDate?.toISOString() ?? new Date().toISOString(),
+        hardwareConcurrency: 1,
+        dataOrigin: 'TraceEvents',
+        ...metadata,
+    };
+}
 /**
  * Creates a complete trace file container with metadata.
  * @param opt - Trace file configuration
@@ -170,10 +203,88 @@ export const measureToSpanEvents = (entry, opt) => getSpan({
 export const getTraceFile = (opt) => ({
     traceEvents: opt.traceEvents,
     displayTimeUnit: 'ms',
-    metadata: {
-        source: 'Node.js UserTiming',
-        startTime: opt.startTime ?? new Date().toISOString(),
-        hardwareConcurrency: os.cpus().length,
-    },
+    metadata: getTraceMetadata(opt.startTime ? new Date(opt.startTime) : new Date(), opt.metadata),
 });
+/**
+ * Processes the detail property of an object using a custom processor function.
+ * @template T - Object type that may contain a detail property
+ * @param target - Object containing the detail property to process
+ * @param processor - Function to transform the detail value
+ * @returns New object with processed detail property, or original object if no detail
+ */
+function processDetail(target, processor) {
+    if (target.detail != null &&
+        (typeof target.detail === 'string' || typeof target.detail === 'object')) {
+        return { ...target, detail: processor(target.detail) };
+    }
+    return target;
+}
+/**
+ * Decodes a JSON string detail property back to its original object form.
+ * @param target - Object containing a detail property as a JSON string
+ * @returns UserTimingDetail with the detail property parsed from JSON
+ */
+export function decodeDetail(target) {
+    return processDetail(target, detail => typeof detail === 'string'
+        ? JSON.parse(detail)
+        : detail);
+}
+/**
+ * Encodes object detail properties to JSON strings for storage/transmission.
+ * @param target - UserTimingDetail object with detail property to encode
+ * @returns UserTimingDetail with object details converted to JSON strings
+ */
+export function encodeDetail(target) {
+    return processDetail(target, (detail) => typeof detail === 'object'
+        ? JSON.stringify(detail)
+        : detail);
+}
+/**
+ * Decodes a raw trace event with JSON string details back to typed UserTimingTraceEvent.
+ * Parses detail properties from JSON strings to objects.
+ * @param event - Raw trace event with string-encoded details
+ * @returns UserTimingTraceEvent with parsed detail objects
+ */
+export function decodeTraceEvent({ args, ...rest }) {
+    if (!args) {
+        return rest;
+    }
+    const processedArgs = decodeDetail(args);
+    if ('data' in args && args.data && typeof args.data === 'object') {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        return {
+            ...rest,
+            args: {
+                ...processedArgs,
+                data: decodeDetail(args.data),
+            },
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return { ...rest, args: processedArgs };
+}
+/**
+ * Encodes a UserTimingTraceEvent to raw format with JSON string details.
+ * Converts object details to JSON strings for storage/transmission.
+ * @param event - UserTimingTraceEvent with object details
+ * @returns TraceEventRaw with string-encoded details
+ */
+export function encodeTraceEvent({ args, ...rest }) {
+    if (!args) {
+        return rest;
+    }
+    const processedArgs = encodeDetail(args);
+    if ('data' in args && args.data && typeof args.data === 'object') {
+        const result = {
+            ...rest,
+            args: {
+                ...processedArgs,
+                data: encodeDetail(args.data),
+            },
+        };
+        return result;
+    }
+    const result = { ...rest, args: processedArgs };
+    return result;
+}
 //# sourceMappingURL=trace-file-utils.js.map

package/src/lib/profiler/trace-file-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-file-utils.js","sourceRoot":"","sources":["../../../../src/lib/profiler/trace-file-utils.ts"],"names":[],"mappings":"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"}

package/src/lib/{trace-file.type.d.ts → profiler/trace-file.type.d.ts}

@@ -1,4 +1,4 @@
-import type { UserTimingDetail } from './user-timing-extensibility-api.type.js';
+import type { UserTimingDetail } from '../user-timing-extensibility-api.type.js';
 /**
  * Arguments for instant trace events.
  * @property {UserTimingDetail} [detail] - Optional user timing detail with DevTools payload
@@ -139,7 +139,11 @@ export type SpanEvent = BeginEvent | EndEvent;
 /**
  * Union type of all trace event types.
  */
-export type TraceEvent = InstantEvent | CompleteEvent | SpanEvent | InstantEventTracingStartedInBrowser;
+export type UserTimingTraceEvent = InstantEvent | SpanEvent;
+/**
+ * All trace events including system events added during finalization.
+ */
+export type TraceEvent = UserTimingTraceEvent | CompleteEvent | InstantEventTracingStartedInBrowser;
 /**
  * Raw arguments format for trace events before processing.
  * Either contains a detail string directly or nested in a data object.

package/src/lib/profiler/trace-file.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-file.type.js","sourceRoot":"","sources":["../../../../src/lib/profiler/trace-file.type.ts"],"names":[],"mappings":""}

package/src/lib/profiler/wal-json-trace.d.ts

@@ -0,0 +1,25 @@
+import type { InvalidEntry } from '../wal.js';
+import type { UserTimingTraceEvent } from './trace-file.type.js';
+/**
+ * Generates a complete Chrome DevTools trace file content as JSON string.
+ * Adds margin events around the trace events and includes metadata.
+ * @param events - Array of user timing trace events to include
+ * @param metadata - Optional custom metadata to include in the trace file
+ * @returns JSON string representation of the complete trace file
+ */
+export declare function generateTraceContent(events: UserTimingTraceEvent[], metadata?: Record<string, unknown>): string;
+/**
+ * Creates a WAL (Write-Ahead Logging) format configuration for Chrome DevTools trace files.
+ * Automatically finalizes shards into complete trace files with proper metadata and margin events.
+ * @returns WalFormat configuration object with baseName, codec, extensions, and finalizer
+ */
+export declare function traceEventWalFormat(): {
+    baseName: string;
+    walExtension: string;
+    finalExtension: string;
+    codec: {
+        encode: (event: UserTimingTraceEvent) => string;
+        decode: (json: string) => UserTimingTraceEvent;
+    };
+    finalizer: (records: (UserTimingTraceEvent | InvalidEntry<string>)[], metadata?: Record<string, unknown>) => string;
+};