@voxpelli/type-helpers

My personal type helpers

Usage

JSDoc / Types in JS

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

Or, in modern TypeScript versions:

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

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
  }
}

Function types

• FunctionWithoutFirstParameter<T> – creates a new function type without the first parameter while preserving the return type
• ParametersWithoutTheFirst<T> – extracts the parameter tuple of a function type without the first parameter

Object types

• IsEmptyObject<T> – checks if a type is an empty object (originally from type-fest)
• ObjectEntries<T> – an array of ObjectEntry<T>, more similar to what Object.entries() returns
• ObjectEntry<T> – a typed equivalent to all individual items 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

Utility types

• Equal<A, B> – if A extends B, then resolves to A, else resolved to never
• MaybePromised<T> – resolves to T | Promise<T>
• Simplify<T> – flattens intersection types for cleaner display (originally from type-fest)

Verification types

Type helpers for compile-time validation of type relationships and constraints.

• VerifyObjectHasTypeProperty<Superset, [RequireLiteralStrings=false]> – validates that a type has a type: string property, optionally rejecting generic string in favor of string literals (useful for discriminated unions)
• VerifySuperset<Base, Superset> – validates that Superset is assignable to Base at compile-time

Used by

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

Similar modules

• @voxpelli/typed-utils – contains some useful types like LiteralTypeOf<T> and LiteralTypes (that used to belong to this module)
• type-fest – a large collection of type helpers