Typescript types?

[sargunv]

First, I want to say I'm really liking Honeycomb so far! I used to use Scuba at FB and Honeycomb has been pretty good at filling that gap in my toolkit since leaving.

I see Typescript type definitions were added in #52 and then removed in #66. Curious, was there an issue with those types?

I'm working on instrumenting all our services with Honeycomb, but our new services are 100% Typescript with strict linting with type checking, making integrating Libhoney (and Beeline) a bit of a hassle. Happy to see Beeline now has a PR to add type definitions but I'd love to see the same in Libhoney too, as I want to log some events independently of what Beeline provides.

[vreynolds]

Hey @sargunv, thanks for the feedback!

With regards to that earlier definition file: it seems it got out of date and was blocking other functionality at a time that the team didn't have bandwidth to keep it up.

There's certainly an appetite for TS definitions out there, and it's on the list of potential enhancements. Thanks for submitting the issue, we'll keep it open, so others can +1.

[alamothe]

The API is pretty convoluted, so TypeScript type definitions would help a lot.

[PepijnSenders]

I wrote a typedef myself, feel free to use:

declare module 'libhoney' {
  type LibhoneyOptions = {
    writeKey: string;
    dataset: string;
  };

  type FieldValue = string | number | undefined | null;
  type DynamicFieldValue = () => FieldValue;

  type Fields = Record<string, FieldValue>;
  type DynamicFields = Record<string, DynamicFieldValue>;

  /**
   * Represents an individual event to send to Honeycomb.
   */
  class Event {
    public timestamp: string;
    public data: Fields;

    constructor(
      libhoney: Libhoney,
      fields: Fields,
      dynamicFields: DynamicFields
    );

    /**
     * adds a group of field->values to this event.
     */
    add(data: Fields): void;

    /**
     * adds a single field->value mapping to this event.
     */
    addField(name: string, value: FieldValue): Event;

    /**
     * attaches data to an event that is not transmitted to honeycomb, but instead is available
     * when checking the send responses.
     */
    addMetadata(md: Record<string, string>): Event;

    /**
     * Sends this event to honeycomb, sampling if necessary.
     */
    send(): void;

    /**
     * Dispatch an event to be sent to Honeycomb.  Assumes sampling has already happened,
     * and will send every event handed to it.
     */
    sendPresampled(): void;
  }

  /*
   * Allows piecemeal creation of events.
   */
  class Builder {
    constructor(
      libhoney: Libhoney,
      fields: Fields,
      dynamicFields: DynamicFields
    );
    /*
     * adds a group of field->values to the events created from this builder.
     */
    add(fields: Fields & DynamicFields): Builder;
    /*
     * adds a single field->value mapping to the events created from this builder.
     */
    addField(name: string, value: FieldValue): Builder;
    /*
     * adds a single field->dynamic value function, which is invoked to supply values when events
    are created from this builder.
     */
    addDynamicField(
      name: string,
      dynamicFieldValue: DynamicFieldValue
    ): Builder;
    /**
     * creates and sends an event, including all builder fields/dynFields, as well as anything
     * in the optional data parameter.
     */
    sendNow(fields: Fields & DynamicFields): void;
    /*
     * creates and returns a new Event containing all fields/dynFields from this builder, that
    can be further fleshed out and sent on its own.
     */
    newEvent(): Event;
    /*
     * creates and returns a clone of this builder, merged with fields and dynFields passed as
     * arguments.
     */
    newBuilder(fields: Fields, dynamicFields?: DynamicFields): Builder;
  }

  /*
   * libhoney aims to make it as easy as possible to create events and send them on into Honeycomb.
   */
  class Libhoney {
    public sampleRate: number;
    public dataset: number;
    public writeKey: string;
    public apiHost: string;
    /*
     * Constructs a libhoney context in order to configure default behavior,
     * though each of its members (`apiHost`, `writeKey`, `dataset`, and
     * `sampleRate`) may in fact be overridden on a specific Builder or Event.
     */
    constructor(options: LibhoneyOptions);
    add: Builder['add'];
    addField: Builder['addField'];
    addDynamicField: Builder['addDynamicField'];
    sendNow: Builder['sendNow'];
    newEvent: Builder['newEvent'];
    newBuilder: Builder['newBuilder'];
    /**
     * Allows you to easily wait for everything to be sent to Honeycomb (and for responses to come back for
     * events). Also initializes a transmission instance for libhoney to use, so any events sent
     * after a call to flush will not be waited on.
     */
    flush(): Promise<void>;
  }

  export default Libhoney;
}