Styling, export and integration

TypeScript declarations

123 of 136

The types are the reference

plotscope is written in TypeScript and ships its declarations in the package. There is nothing to install beside it and no @types package to keep in step. Every argument table and call signature on this site is generated from those declarations, so what an editor shows and what these pages show are the same text.

The code on this page is compiled when the site is built. Each @ts-expect-error marks a line the compiler must refuse, and the build fails if it ever accepts one.

A handle is not a number

An upload returns a handle, and a handle says what it is a handle to. Underneath each is a number. In the types they are different things, so a buffer cannot be shown as a cloud:

export function handles(plot: Plot, cloud: PointsHandle, column: BufferHandle): void {
  plot.showPoints(cloud);
  // @ts-expect-error a buffer is not a cloud, though both are a number underneath
  plot.showPoints(column);
  // @ts-expect-error and a number that was never issued is not a handle at all
  plot.showPoints(7);
}

One tag, not two shapes

Where a value is one of several forms, a field says which. A window onto a growing series is so many samples or so many seconds, and there is no way to write both:

export const newest: ChartWindow = { kind: "samples", of: 600 };
// @ts-expect-error told apart by `kind`, so there is no way to write both at once
export const both: ChartWindow = { samples: 600, seconds: 10 };

A chart is the same, at a larger size. kind decides which fields it takes, so a gauge is not offered a line chart's axes and the editor completes only what that kind reads.

What comes back is complete

Optional fields are for what a page writes. Anything the plot hands back has every field, every time, and where it has nothing to say the type says null:

export function under(plot: Plot, x: number, y: number): number {
  const hit = plot.hitTest(x, y);
  // @ts-expect-error nothing under the pointer is `null`, in the type
  const unchecked: number = hit.index;
  return hit === null ? -1 : hit.index;
}

Answers that come in several forms carry a tag to narrow on, status on a licence and type on an event, and each form has only its own fields:

export function licensee(licence: LicenceStatus): string | null {
  // @ts-expect-error only an active or lapsed licence has a licensee
  const unchecked: string = licence.licensee;
  // `type` and `status` tags narrow, so each branch sees only its own fields.
  return licence.status === "active" ? licence.licensee : null;
}

Strict settings

The declarations are written under strict, exactOptionalPropertyTypes and noUncheckedIndexedAccess, and hold under all three in a project that turns them on. None of them is required.