npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@proedis/types

v2.1.1

Published

Shared TypeScript type primitives for the Proedis suite

Readme

@proedis/types

The handful of type primitives every Proedis package agrees on, so Nullable<T> means the same thing in all of them. 🧬

npm license


✨ What's in the box

Fifteen types. No runtime logic, no dependencies, nothing to configure. 🪶

  • Absence — Nullable, Nillable
  • Value shapes — Primitive, Awaitable
  • Object shapes — AnyObject, ValueOf, DeepPartial
  • Object navigation — ObjectPath, ValueAtPath, the pair that makes getValueAt('a.b.c') type safe
  • Key extraction — RequiredKeys, UnionToTuple, IsSingleMember, RootPathFor, the type-level arithmetic a generated API surface needs
  • Classes — Instantiable
  • Environment — Environment

📦 Installation

yarn add @proedis/types

It belongs in dependencies, not devDependencies: if any of your published .d.ts files mentions one of these types, your consumers have to be able to resolve it too.

🚀 Quick start

import type { DeepPartial, Nullable, ObjectPath, ValueAtPath } from '@proedis/types';

interface User {
  id: string;
  profile: { displayName: string; avatar: Nullable<string> };
}

/** A typed accessor: the return type follows the path the caller asked for */
declare function read<T extends AnyObject, P extends ObjectPath<T>>(source: T, path: P): ValueAtPath<T, P>;

const name = read(user, 'profile.displayName'); // string
const oops = read(user, 'profile.nickname');    // ❌ compile error, no such path

/** A partial override of a deeply nested settings object */
const overrides: DeepPartial<User> = { profile: { avatar: null } };

📖 API

Absence

| Type | Resolves to | Use it when | | --- | --- | --- | | Nullable<T> | T \| null | null is a meaningful, expected outcome | | Nillable<T> | T \| null \| undefined | the two flavours of absence are interchangeable — which is most of the time |

Value shapes

| Type | Resolves to | Use it when | | --- | --- | --- | | Primitive | string \| number \| bigint \| boolean \| symbol \| null \| undefined | you need the terminal branch of a recursive type | | Awaitable<T> | T \| Promise<T> | you always await a user supplied callback, and want to let it stay synchronous |

Object shapes

AnyObject

type AnyObject = { [key: string]: any };

The deliberate escape hatch used as a generic constraint across the suite (<T extends AnyObject>), where the meaning is "some object, whichever one you pass".

⚠️ It is not the type for a variable you are about to read from. That is Record<string, unknown>, and it will make the compiler ask you the questions AnyObject lets you skip.

ValueOf<T>

const Role = { admin: 'admin', guest: 'guest' } as const;

type Role = ValueOf<typeof Role>; // 'admin' | 'guest'

The companion of keyof, and the idiomatic way to turn a const object used as an enum into the type of its members.

DeepPartial<T>

Recursively marks every property optional. Arrays are walked through their element type, while primitives, Date, RegExp and functions are handed back untouched — mapping over the members of a Date produces an object that satisfies nothing.

type Settings = { server: { port: number }; createdAt: Date; tags: string[] };

type Overrides = DeepPartial<Settings>;
// { server?: { port?: number }; createdAt?: Date; tags?: string[] }

Object navigation

ObjectPath<T>

Every dot notation path that can be walked inside an object, as a string literal union. Array and tuple indexes are included, so a path can cross a collection — and because the result is a literal union, your editor autocompletes the valid paths while you type.

type Paths = ObjectPath<{ server: { port: number }; tags: string[] }>;
// 'server' | 'server.port' | 'tags' | `tags.${number}`

ValueAtPath<T, P>

The type of the value found at a given path. Pair it with ObjectPath<T> to type an accessor whose return type follows its argument, the way getValueAt and setValueAt in @proedis/utils do.

Key extraction

The four that exist because generated code asks questions about its own shape, and re-deriving them per project is how a project ends up with three slightly different versions.

RequiredKeys<T>

The keys an object demands, as a literal union — never when it demands nothing. That is what lets a signature make its own parameter optional exactly when the shape it describes has no required key:

type Query = { page?: number; sort?: string };
type Route = { id: string; tab?: string };

type A = RequiredKeys<Query>;  // never
type B = RequiredKeys<Route>;  // 'id'

declare function build<P>(path: string, ...params: RequiredKeys<P> extends never ? [ P? ] : [ P ]): string;

build<Query>('/projects');              // ok, the query is optional
build<Route>('/projects/{id}');         // error, the route params are not

UnionToTuple<U> and IsSingleMember<U>

type Methods = UnionToTuple<'GET' | 'POST'>;   // ['GET', 'POST'] — or ['POST', 'GET']
type One = IsSingleMember<'GET'>;              // true
type Two = IsSingleMember<'GET' | 'POST'>;     // false

IsSingleMember answers the question T extends U cannot: a union is assignable to itself, so counting the members is the only way. The use case is a generated operation — one that documents a single HTTP method can have that method defaulted, one that documents several cannot.

UnionToTuple is what makes the count possible, riding the contravariance of function parameters to peel off one member at a time. ⚠️ The resulting order is an implementation detail of the compiler: treat it as a set that happens to have a length, never as a list.

RootPathFor<U, Suffix>

type Paths = 'projects' | 'projects/{id}' | 'tasks' | 'tasks/{id}';

type Roots = RootPathFor<Paths, '/{id}'>;
// 'projects' | 'tasks'

Given every path an API documents, it answers which resources have a given sub-route, and hands back the prefix — so the parent path can be built from the child one instead of being spelled twice.

Classes

Instantiable<T>

The class object itself, not one of its instances. For any API that receives a class to build later — a factory, a container, an error a guard will throw:

function create<T extends AnyObject>(
  ctor: Instantiable<T>,
  ...args: ConstructorParameters<Instantiable<T>>
): T {
  return new ctor(...args);
}

const error = create(RangeError, 'out of bounds');

Environment

Environment

type Environment = 'development' | 'production' | 'test' | 'staging';

The values process.env.NODE_ENV is expected to carry. Configuration objects across the suite accept Partial<Record<Environment, T>> wherever a setting may differ per environment.

🧠 Why every type has a constant next to it

Look at the source and you will find this shape repeated:

export type Nullable<T> = T | null;
export const Nullable = Object;

The constant is not something you should ever use. It exists so that a plain value import stays safe at runtime:

import { Nullable } from '@proedis/types'; // no `type` keyword

Under isolatedModules — which is to say under esbuild, SWC, Babel and every bundler that strips types one file at a time — that statement survives compilation and would resolve a binding that was never emitted. TypeScript merges the type and the constant into a single name, so nothing about the type side changes.

💡 Write import type { … } anyway. It states the intent, and the import disappears completely.

🔀 Migrating to 2.x

| Change | What to do | | --- | --- | | RecursivePartial<T> → DeepPartial<T> | Rename. The old name still works as a @deprecated alias forwarding to the new one, and will be removed in the next major. | | DeepPartial no longer recurses into Date, RegExp and functions | Nothing, unless you were relying on RecursivePartial<Date> producing an object of optional methods — which never typechecked against a real Date. | | The package now ships compiled JavaScript instead of raw .ts | Nothing for a normal import. It stops assuming your bundler is willing to transpile TypeScript found inside node_modules, and adds a proper exports map. | | New: Primitive, Awaitable, ValueOf | Nothing — purely additive. |

🤝 Compatibility

| Requirement | Range | | --- | --- | | typescript | >=5.2.0 | | Runtime | anything — the emitted JavaScript is a handful of constant assignments |

📄 License

MIT © Proedis S.r.l.