@mdor/types

Reusable, zero-runtime TypeScript utility types for MDOR projects. The package is type-only: use import type and no JavaScript is added to the application bundle.

Requirements

• Node.js 22.13 or newer for package tooling
• npm 10 or newer
• TypeScript 5.5.4 or newer

Install

npm install --save-dev @mdor/types

TypeScript is a peer dependency. npm 7 and newer installs compatible peers automatically; other package managers may require installing TypeScript explicitly.

Examples

Values and asynchronous results

import type { Async, Maybe, MaybeAsync } from "@mdor/types";

export type HookResult = Async<void>;
export type Refetch = MaybeAsync<void>;
export type SelectedId = Maybe<string>;

Object shape utilities

import type { MakeOptional, MakeRequired, MergeLeft, MergeRight } from "@mdor/types";

interface Settings {
  displayName: string;
  notificationsEnabled: boolean;
}

export type SettingsDraft = MakeOptional<Settings, "notificationsEnabled">;
export type SettingsSaved = MakeRequired<SettingsDraft, "notificationsEnabled">;
export type SettingsWithDefaults = MergeRight<Settings, { displayName?: string }>;
export type SettingsPreferDefaults = MergeLeft<{ displayName?: string }, Settings>;

Readonly and mutable variants

import type { MakeMutable, MakeReadonly } from "@mdor/types";

interface Cart {
  items: { id: string; quantity: number }[];
}

export type FrozenCart = MakeReadonly<Cart>;
export type EditableCart = MakeMutable<FrozenCart>;

JSON-safe data

import type { JSONObject, JSONValue } from "@mdor/types";

const metadata: JSONObject = {
  active: true,
  labels: ["new", "featured"],
};

function serialize(value: JSONValue): string {
  return JSON.stringify(value);
}

Property and value lookups

import type { MapByType, ObjectByProp, ValueOf } from "@mdor/types";

interface Point {
  x: number;
  y: number;
}

type Coordinate = ValueOf<Point>;
type PointObject = ObjectByProp<Point>;
type PointMap = MapByType<Point>;

Included types

• Value wrappers: Primitive, Maybe, Defined, Async, MaybeAsync, and Throwable.
• JSON: JSONPrimitive, JSONArray, JSONObject, and JSONValue.
• Object utilities: Simplify, MergeLeft, MergeRight, MakeReadonly, MakeMutable, MakeOptional, and MakeRequired.
• Value and property lookups: ValueOf, ObjectByProp, and MapByType.

Suggestions for future additions

Add types when at least two packages share a real use case. Good candidates are:

• DeepRequired and DeepNullable for normalized configuration data.
• Paths and PathValue for typed object-path APIs.
• AsyncFunction and AsyncReturnType for job and handler abstractions.
• Result<Success, Failure> for explicit operation outcomes.
• Brand/Opaque for nominal typing when structural typing is not enough.
• String helpers such as CamelCase only when a runtime naming API needs an equivalent compile-time type.

Avoid adding domain models, framework-specific types, or utilities already provided clearly by TypeScript itself.

Validate and release

npm run typecheck --workspace @mdor/types
npm test --workspace @mdor/types
npm pack --workspace @mdor/types --dry-run
npm run release-patch-try --workspace @mdor/types

Publishing requires npm authentication with access to the @mdor organization.