@loke/context

A typescript version of the go context package.

Installation

npm install @loke/context

Usage

import * as context from "@loke/context";
import { Context } from "@loke/context";

async function getUser(cxt: Context, id: string): Promise<unknown> {
  const { ctx, abort } = context.withTimeout(cxt, 1000);

  try {
    const res = await fetch(`/users/${id}`, { signal: ctx.signal });

    if (res.ok) {
      throw new Error("not ok");
    }

    return await res.json();
  } finally {
    abort();
  }
}

API

Context

type Context = {
  readonly signal?: AbortSignal;
  readonly deadline?: number;
};

Abortable

type Abortable = {
  readonly ctx: Context;
  readonly abort: () => void;
};

background

const background: Context;

TODO

const TODO: Context;

withAbort(parent: Context): Abortable;

• parent - The parent context to extend.

Extends the parent context with an abortable signal. The signal is aborted when the returned abort function is called or when the parent context is aborted.

The returned abort function MUST be called to avoid memory leaks.

withTimeout(parent: Context, duration: number): Abortable;

• parent - The parent context to extend.
• duration - The timeout in milliseconds.

Extends the parent context with an abortable signal. The signal is aborted when the returned abort function is called, when the parent context is aborted or when the timeout is reached.

The returned abort function MUST be called to avoid memory leaks.

withDeadline(parent: Context, deadline: Date | number): Abortable;

• parent - The parent context to extend.
• deadline - The deadline as a date or a timestamp in milliseconds.

Extends the parent context with an abortable signal. The signal is aborted when the returned abort function is called, when the parent context is aborted or when the deadline is reached.

The returned abort function MUST be called to avoid memory leaks.

withValues(parent: Context, values: Record<symbol | string, unknown>): Context;

• parent - The parent context to extend.
• values - The values to add to the context.

Extends the parent context with a set of values. To help with type safety the keys should be symbols, and accessed using custom getters. You can also use a custom setter to ensure that the values are of the correct type, this may be overkill if you only set the values once.

Example

const localeKey = Symbol("locale");

export function withLocale(parent: Context, locale: string): Context {
  return context.withValues(parent, {
    [localeKey]: locale,
  });
}

export function getLocale(ctx: Context): string {
  if (localeKey in ctx) {
    return ctx[localeKey];
  } else {
    return "en";
  }
}

Well known values API

requestIdKey

const requestIdKey: symbol;

Example

const ctx = context.withValues(context.background, {
  [context.requestIdKey]: "1234",
});

getRequestId(ctx: Context): string | undefined;

Example

const requestId = getRequestId(ctx);