Grok

An expressive series of utilities for language like types.

The meta programming within TypeScript using types can be very powerful and extremely helpful for enforcing strong types and safer builds. The goal of Grok is to remove some of the cognitive load that comes with trying to express these types by introducing a more verbose language syntax (as helpers).

Example

At core of Grok is an abstraction around the extends expression to introduce the concept of an if-statement. With only this Grok has grown to be extremely powerful and diverse in its offering.

In simple cases Grok might be considered over complicated but it really shines in complex type logic that changes depending on given inputs.

type MyValue<T> = (
  Grok.If<
    Grok.Value.IsExtending<T, 'foo'>,
    'its foo',
    Grok.If<
      Grok.Value.IsExtending<T, 'bar'>,
      'its bar',
      'its something'
    >,
  >
);
)

More logical helpers and value comparitors are available:

Logic & Expressions

Grok.If
Grok.And
Grok.Or
Grok.Not
Grok.Has

Type Helpers

Grok.Merge
Grok.Union
Grok.Union.FromArray
Grok.Union.RemoveValue
Grok.Union.Has
Grok.Record.RemoveValue
Grok.Record.ReplaceAny
Grok.Record.IsKeyOptional

Value Comparisons

Grok.Value.IsExtending
Grok.Value.IsExactly
Grok.Value.IsAny
Grok.Value.IsNever
Grok.Value.IsUnknown
Grok.Value.IsUndefined
Grok.Value.IsBoolean
Grok.Value.IsTrue
Grok.Value.IsFalse

Constraints

Grok.Constraint.ObjectLike
Grok.Constraint.FunctionLike
Grok.Constraint.ArrayWithOneOrMore<T>

Utility Helpers

Maybe to add undefined (opposite of NonNullable in typescript core)
Nullable to add null (opposite of NonNullable in typescript core)
Mutable to remove readonly (opposite of Readonly in typescript core)
Provider<T> to represent a function that returns its given value, alias () => T

Functional Helpers

noop() a function that has no-operation
never() a never assertion
okv() a key accessor
okvr() a key accessor with validation and requirements
okey() a type keyof assistance
union() a union value enforcement
provide() a helper for creating Provider<T>

Testing Helpers

fn()
instance()
partial() a Partial<T> to T disguise

Testing Helpers (types)

Grok.Assert for asserting values.
Grok.Assert.IsTrue for asserting a value is true.
Grok.Assert.IsFalse for asserting a value is false.

Documentation

Functional Helpers

A series of modular functional helpers and utilities are available also. These are all exported from the main entrypoint and as a modular path export that will allow for better tree shaking.

`noop`

A function that can be used to represent a no-operation.

`never`

For use with union exhaustiveness checking which will cause TypeScript to error when the given value is not of type never. This function simply throws an error of NeverReachAssertionError when compiled which should be caught by your error reporting tool of choice.

import { never } from '@matt-usurp/grok';
// or
import { never } from '@matt-usurp/grok/core/assert-never';

declare const union: 1 | 2

if (union === 1 || union === 2) {
  // do something
}

never(union);

Introducing a new value to union will cause never to raise an error at build time.

`okv`

An accessor utility for retreiving values from object sources by key. This is a factory that returns a function that can be called multiple times to retrieve values from the source by key.

There is a runtime safe version of this called okvr!

import { okv } from '@matt-usurp/grok';
// or
import { okv } from '@matt-usurp/grok/core/object';

declare const mapping: {
  readonly name: string;
  readonly age?: number;
}

okv(mapping)('name') // mapping.name [string]
okv(mapping)('age', 26) // mapping.age or 26 if undefined

`okvr`

A runtime safe version of okv() that will throw errors when keys are not available in the given source object.

import { okvr } from '@matt-usurp/grok';
// or
import { okvr } from '@matt-usurp/grok/core/object';

declare const mapping: {
  readonly name: string;
  readonly age?: number;
}

// mapping.name must not be undefined
okvr(mapping)('name')

// mapping.name will be replaced with fallback if undefined
// an error is thrown if fallback was undefined also.
okvr(mapping)('name', fallback)

// custom validator function is provided checking values are not null also
// mapping.age is verified, an error is thrown if its undefined or null (validator function)
okvr(mapping, ['age'], (v) => v !== null)

// mapping.age is verified, an error is thrown if its undefined
// mapping.name can be undefined, and fallback can be used.
okvr(mapping, ['age'])('name', fallback)

The okvr function is perfect for accessing keys against process.env when working in the context of Node.

const env = okvr(process.env);

env('SOME_AVAILABLE_VAR');
env('SOME_UNDEFINED_VAR', fallback);
env('ANOTHER_UNDEFINED_VAR'); // throws

`okey`

Allows for type-safe strings that are keys of an object. A functional variant of the <keyof SomeObject>'name' which cannot be used with JSX`.

import { okey } from '@matt-usurp/grok';
// or
import { okey } from '@matt-usurp/grok/core/object';

declare const mapping: {
  readonly name: string;
  readonly age?: number;
}

// the same
<keyof typeof mapping>'name';
okey<typeof mapping>('name');

`union`

A unique utility for times where you want to convert a union of strings to a string[] at runtime. This is done by forcing the values to be defined through a mapping that can be enforced at compile time. Unlike using MyUnion[] which does not enforce all values are present within the array.

import { union } from '@matt-usurp/grok';
// or
import { union } from '@matt-usurp/grok/core/value';

type MyUnion = 'name' | 'age';

const values = union<MyUnion>({
  name: undefined,
  age: undefined,
});

values; // ['name', 'age']

`provide`

A utility that creates functions that are compatible with a Provider<T>. A Provider<T> is a essentially a value wrapped in a function with no parameters. When called it will return the given value.

import { provide } from '@matt-usurp/grok'
// or
import { provide } from '@matt-usurp/grok/core/value';

const age = provide(30)

age(); // 30

Testing Helpers

A series of helpers and utlities for enriching your testing experience.

`fn`

An extension on vi.fn() that allows you to pass your function type as the generic and it will resolve the arguments and result for you.

import { fn } from '@matt-usurp/grok/testing';

type MyFunction = (age: number) => boolean;

const mock = fn<MyFunction>();

mock; // Mock<boolean, [age: number]>

expect(mock).toBeCalledTimes(0);

`instance`

A utiltity that disguises an object as the given type T. Optionally you can provide a string[] of functions and they will be automatically set using fn() above.

Note, this is a disguise and all properties are undefined unless set manually after calling. This function is inteded to minimise the amount of type casting and boiler plate needed for creating simplistic mocks of complex classes or types.

import { instance } from '@matt-usurp/grok/testing';

class Person {
  public readonly name: string;
  public readonly age: number;

  public speak(): void { .. };
  public walk(steps: number): boolean { .. };
};

const value = instance<Person>([
  'speak',
]);

value; // { speak: Mock }
value.speak(); // returns undefined

expect(value.speak).toBeCalledTimes(1);

`partial`

This is a utility that works similar to instance() but in a more simplified way, it can be better expressed through the type <T>(in: Partial<T>) => T. Again, this is intended for use with testing where a full T is needed but your test is asserting just a Partial<T>.

This is intended more of a utility around types and less about functionality.

import { partial } from '@matt-usurp/grok/testing';

type Person = {
  readonly name: string;
  readonly age: number;
  readonly gender: unknown;
}

const value = partial<Person>({
  name: 'Tony Stark',
});

value; // Person
value.name; // 'Tony Stark'
value.age; // undefined