@voxpelli/type-helpers

My personal type helpers

Usage

JSDoc / Types in JS

/** @typedef {import('@voxpelli/type-helpers').PartialKeys} PartialKeys */

TypeScript

import type { PartialKeys } from '@voxpelli/type-helpers';

Declaration types

A mechanism for third-party extendible discriminated unions.

• AnyDeclaration<Declarations, [DeclarationsExtras={}]> – returns a union of all valid declarations in Declarations
• AnyDeclarationType<Declarations, [DeclarationsExtras={}]> – returns a union of the type names from all valid declarations in Declarations
• ValidDeclaration<TypeName, Declarations, [DeclarationsExtras={}]> – the base type of a valid declaration for Declarations / DeclarationsExtras that also validates that TypeName exists as a valid declaration in Declarations

Details on how to use declarations

Valid declarations

1. Are part of Declarations
2. Complies with the DeclarationsExtras type
3. Has a type key that matches a declarations key in Declarations

Declaration types example

Imaginary module @voxpelli/foo:

import type {
  AnyDeclaration,
  AnyDeclarationType,
  ValidDeclaration
} from '@voxpelli/type-helpers';

interface FooDeclarationExtras {
  value: unknown
}

export interface FooDeclarations {
  bar: FooDeclaration<'bar', { abc: 123 }>,
  // This is a recommended addition, ensuring consumers stay alert and are aware
  // that extensions here can be of all kinds of types
  unknown: FooDeclaration<'unknown', unknown>,
}

export type AnyFooDeclaration = AnyDeclaration<FooDeclarations, FooDeclarationExtras>;
export type AnyFooDeclarationType = AnyDeclarationType<FooDeclarations, FooDeclarationExtras>;

export interface FooDeclaration<TypeName extends AnyFooDeclarationType, Value>
  extends ValidDeclaration<TypeName, FooDeclarations, FooDeclarationExtras>
{
  value: Value
}

Third party extension:

import type { FooDeclaration } from '@voxpelli/foo';

declare module '@voxpelli/foo' {
  interface FooDeclarations {
    xyz: FooDeclaration<'xyz', { xyz: true }>
  }
}

Usage as a :

/**
 * @param {AnyFooDeclaration} foo
 */
function timeToFoo (foo) {
  switch (foo.type) {
    case 'bar':
      // foo.value.abc will be know to exist and be a number
      break;
    case 'xyz':
      // If the third party extension has been included, then foo.value.xyz will be know to exist here and be a boolean
      break;
    default:
      // foo.value is eg. unknown here
  }
}

Object types

• ObjectEntry<T> – a typed equivalent to all invidiual items Object.entries() returns
• ObjectEntries<T> – an array of ObjectEntry<T>, mmore similar to what Object.entries() returns
• ObjectFromEntries<T> – a typed equivalent of what Object.fromEntries() returns
• PartialKeys<Foo, 'abc'> – makes the key abc of Foo optional
• UnknownObjectEntry – the least specific entry for ObjectFromEntries<T> and what T needs to be a subset of there

String types

• NonGenericString<T, [ErrorMessage]> – ensures that T is not a generic string (and as such likely a string literal)
• NonGenericStringArray<T, [ErrorMessage]> – similar to NonGenericString but with T being an Array / ReadonlyArray

Util types

• Equal<A, B> – if A extends B, then resolves to A, else resolved to never
• LiteralTypeOf<T> – resolves to a string literal that matches the typeof operator
• MaybePromised<T> – resolves to T | Promise<T>

Used by

• @voxpelli/typed-utils – my personal (type-enabled) utils / helpers
• umzeption – my original project for the initial types of this module

Similar modules

• type-fest – a large colelction of type helpers