@datadog/vis-core

@datadog/vis-core

This package offers:

• The core DataFrame tabular data structure used by other @datadog/vis-* libraries. Features type inference.
• Datadog styles (color palettes, colors).
• No external dependencies.

It is under active development, and subject to breaking changes.

Install

yarn add @datadog/vis-core

Basic Usage

import { DataFrame } from "@datadog/vis-core";

const now = Date.now();
const oneHourAgo = now - 3600 * 1000;
const twoHoursAgo = now - 7200 * 1000;

// Scalar columns can contain numbers or nulls.
const columnConfig = [
  {
    id: "timestamp",
    kind: "scalar",
    values: [now, oneHourAgo, twoHoursAgo, now, oneHourAgo, twoHoursAgo],
    meta: {},
  },
  {
    id: "value",
    kind: "scalar",
    values: [0, 60, 80, 10, 20, 30],
    meta: {},
  },
  {
    id: "key",
    kind: "string",
    values: ["Alpha", "Alpha", "Alpha", "Beta", "Beta", "Beta"],
    meta: {},
  },
];

const dataFrame = DataFrame.fromColumns(columnConfig);

To read values back out:

const rows = dataFrame.getRows();
const values = dataFrame.getColumnValues("timestamp");

Advanced Usage (Typescript)

The DataFrame typescript generic optionally accepts an array or tuple type of Columns.

Using these types is not required. However, using them may improve the quality of the type-hinting provided by your editor.

• Column Kinds
  • Primitives
    • Boolean: true / false
    • String
    • Float32: Typed arrays
  • Compound
    • Scalar: number | null
    • Object: Any javascript object

Each Column type also accepts a generic for ColumnMetadata as a second argument.

For example:

import type {
  DataFrame,
  StringColumn,
  ScalarColumn,
  ObjectColumn,
} from "@datadog/vis-core";

type PermittedColumns =
  | StringColumn<string, { source: "Wikipedia" }>
  | ScalarColumn<string, any> // no metadata
  | ObjectColumn<
      string,
      { type: "unknown"; source: "external" },
      { min: number }
    >;

interface TableMeta {
  source: "public";
  [key: string]: unknown;
}

type CustomDataFrame = DataFrame<PermittedColumns[], TableMeta>;

const columnConfig = [
  {
    id: "stats",
    kind: "object" as const,
    values: [{ min: 0 }, { min: 0 }, { min: 0 }, { min: 0 }],
    meta: { type: "unknown" as const, source: "external" as const },
  },
  {
    id: "value",
    kind: "scalar" as const,
    values: [0, 80, 10, 30],
    meta: {},
  },
  {
    id: "key",
    kind: "string" as const,
    values: ["Alpha", "Alpha", "Beta", "Beta"],
    meta: { source: "Wikipedia" as const },
  },
];

const dataFrame: CustomDataFrame = DataFrame.fromColumns(columnConfig, {
  source: "public",
});

The full documentation page is under review.