Skyroc Type Utils

English | 简体中文

用于表单处理、路径操作和类型转换的高级 TypeScript 实用类型。提供全面的类型工具集合，通过强大的类型级编程能力增强 TypeScript 的类型系统。

✨ 特性

• 🎯 高级类型工具 - 丰富的工具类型集合，用于复杂的类型转换
• 📝 表单类型支持 - 专为表单元素和自定义组件设计的类型
• 🛤️ 路径操作 - 类型安全的路径类型，用于嵌套对象访问
• 🔧 函数类型助手 - 从对象中提取和操作函数类型
• 💪 深层类型操作 - 深度可选、深度部分和嵌套类型工具
• 🎨 类型美化 - 使复杂的交叉类型在 IDE 中更易读
• ⚡ 零运行时开销 - 所有工具都是类型级的，零运行时开销

📦 安装

npm install @skyroc/type-utils
# 或
pnpm add @skyroc/type-utils
# 或
yarn add @skyroc/type-utils

🚀 快速开始

import type {
  DeepPartial,
  LeafPaths,
  PathToType,
  OnlyFunctions,
  Prettify
} from '@skyroc/type-utils';

// 嵌套对象的深度部分类型
type User = {
  name: string;
  address: {
    city: string;
    street: string;
  };
};
type PartialUser = DeepPartial<User>;
// { name?: string; address?: { city?: string; street?: string } }

// 嵌套属性的类型安全路径
type UserPaths = LeafPaths<User>;
// "name" | "address.city" | "address.street"

// 从路径获取类型
type CityType = PathToType<User, "address.city">; // string

// 仅提取函数属性
type API = {
  data: string;
  fetch(): Promise<void>;
  update(id: number): void;
};
type APIFunctions = OnlyFunctions<API>;
// { fetch: () => Promise<void>; update: (id: number) => void }

📚 API 参考

函数类型工具

Fn

通用函数类型。

type Fn = (...args: any[]) => any;

Noop

无操作函数类型。

type Noop = () => void;

OnlyFunctions<T>

从对象类型中提取仅包含函数的属性。

interface Foo {
  a: number;
  b?: string;
  c(): void;
  d: (x: number) => string;
  e?: () => void;
}

type FooFunctions = OnlyFunctions<Foo>;
// {
//   c: () => void;
//   d: (x: number) => string;
//   e?: (() => void) | undefined;
// }

FunctionKeys<T>

从对象类型中提取函数属性的键。

interface Foo {
  a: number;
  b?: string;
  c(): void;
  d: (x: number) => string;
  e?: () => void;
}

type FooFnKeys = FunctionKeys<Foo>; // 'c' | 'd' | 'e'

FunctionUnion<T>

创建对象中所有函数类型的联合类型。

interface Foo {
  a: number;
  c(): void;
  d: (x: number) => string;
  e?: () => void;
}

type FooFnUnion = FunctionUnion<Foo>;
// (() => void) | ((x: number) => string) | ((() => void) | undefined)

表单类型工具

CustomElement<T>

表示具有常见输入属性的自定义表单元素。

type CustomElement<T = any> = Partial<HTMLElement> & T & {
  checked?: boolean;
  disabled?: boolean;
  files?: FileList | null;
  focus?: Noop;
  options?: HTMLOptionsCollection;
  type?: string;
  value?: any;
};

FieldElement<T>

所有可能的字段元素的联合类型，包括 HTML 输入和自定义元素。

type FieldElement<T = any> =
  | HTMLInputElement
  | HTMLSelectElement
  | HTMLTextAreaElement
  | CustomElement<T>;

// 在表单处理器中使用
function handleFieldChange(field: FieldElement) {
  console.log(field.value);
}

路径类型工具

LeafPaths<T>

生成类型中所有叶子（非对象）值的可能路径的联合类型。

type FormValues = {
  age: number;
  code: string;
  info: {
    age: number;
    city: string;
    name: string;
  };
  items: {
    id: number;
    label: string;
  }[];
};

type Paths = LeafPaths<FormValues>;
// "age"
// | "code"
// | "info.age"
// | "info.city"
// | "info.name"
// | `items.${number}.id`
// | `items.${number}.label`

AllPaths<T>

生成所有可能路径的联合类型，包括中间对象路径。

type FormValues = {
  age: number;
  info: {
    city: string;
    address: {
      street: string;
    };
  };
};

type Paths = AllPaths<FormValues>;
// "age"
// | "info"
// | "info.city"
// | "info.address"
// | "info.address.street"

PathToType<T, P>

获取特定路径的类型，将对象属性设为可选。

type FormValues = {
  age: number;
  info: {
    age: number;
    city: string;
    address: {
      street: string;
    };
  };
  items: {
    id: number;
    name: string;
  }[];
};

type AgeType = PathToType<FormValues, "age">; // number
type InfoType = PathToType<FormValues, "info">;
// { age?: number; city?: string; address?: { street: string } | undefined }
type ItemType = PathToType<FormValues, "items.0">;
// { id?: number; name?: string }

PathToDeepType<T, P>

获取特定路径的类型，将所有嵌套属性设为深度可选。

type FormValues = {
  info: {
    age: number;
    address: {
      street: string;
      city: string;
    };
  };
};

type InfoType = PathToDeepType<FormValues, "info">;
// {
//   age?: number;
//   address?: {
//     street?: string;
//     city?: string;
//   } | undefined;
// }

ShapeFromPaths<T, Ps>

创建一个新类型，仅包含原始类型中指定的路径。

type FormValues = {
  age: number;
  code: string;
  info: {
    age: number;
    city: string;
    name: string;
  };
  items: {
    id: number;
    label: string;
  }[];
};

type PartialShape = ShapeFromPaths<FormValues, ['age', 'info', 'items.2.label']>;
// {
//   age: number;
//   info: { age?: number; city?: string; name?: string };
//   items: { label?: string }[];
// }

ArrayKeys<T>

从对象中提取数组类型的键。

type Inputs = {
  password: string;
  username: string;
  numbers: number[];
  users: {
    age: number;
    name: string;
  }[];
};

type Arrays = ArrayKeys<Inputs>; // "numbers" | "users"

ArrayElementValue<T, K>

获取数组属性的元素类型。

type Inputs = {
  users: {
    age: number;
    name: string;
  }[];
};

type UserType = ArrayElementValue<Inputs, "users">;
// { age: number; name: string }

通用工具类型

DeepPartial<T>

递归地将类型的所有属性设为可选。

type User = {
  name: string;
  age: number;
  address: {
    city: string;
    street: string;
    zipCode: number;
  };
};

type PartialUser = DeepPartial<User>;
// {
//   name?: string;
//   age?: number;
//   address?: {
//     city?: string;
//     street?: string;
//     zipCode?: number;
//   };
// }

Prettify<T>

展平交叉类型，使其在 IDE 工具提示中更易读。

type A = { a: number };
type B = { b: string };
type C = { c: boolean };

type Raw = A & B & C;
// 悬停时显示: A & B & C (不易读)

type Pretty = Prettify<A & B & C>;
// 悬停时显示: { a: number; b: string; c: boolean } (易读！)

Primitive

所有原始类型的联合类型。

type Primitive =
  | string
  | number
  | boolean
  | bigint
  | symbol
  | null
  | undefined
  | Date
  | Function;

Wrap<K, V>

将值包装在具有特定键的对象中。

type Wrapped = Wrap<"data", number>; // { data: number }
type User = Wrap<"user", { name: string; age: number }>;
// { user: { name: string; age: number } }

MergeUnion<U>

将对象类型的联合类型合并为单个交叉类型。

type Union = { a: number } | { b: string } | { c: boolean };
type Merged = MergeUnion<Union>;
// { a: number; b: string; c: boolean }

KeyToNestedObject<K, V>

将点号表示的键转换为嵌套对象类型。

type Nested = KeyToNestedObject<"a.b.c", number>;
// { a: { b: { c: number } } }

type UserPath = KeyToNestedObject<"user.profile.email", string>;
// { user: { profile: { email: string } } }

🎯 常见用例

类型安全的表单处理

import type { LeafPaths, PathToType, FieldElement } from '@skyroc/type-utils';

type UserForm = {
  username: string;
  email: string;
  profile: {
    firstName: string;
    lastName: string;
    age: number;
  };
  addresses: {
    street: string;
    city: string;
  }[];
};

// 类型安全的字段路径
type FieldPath = LeafPaths<UserForm>;
// "username" | "email" | "profile.firstName" | ...

// 从路径获取字段值类型
function getFieldValue<P extends FieldPath>(
  form: UserForm,
  path: P
): PathToType<UserForm, P> {
  // 实现...
}

// 使用时具有完整的类型安全
const age = getFieldValue(form, "profile.age"); // number
const city = getFieldValue(form, "addresses.0.city"); // string

提取 API 方法

import type { OnlyFunctions, FunctionKeys } from '@skyroc/type-utils';

interface UserService {
  currentUser: User | null;
  isLoading: boolean;
  fetchUser(id: number): Promise<User>;
  updateUser(user: User): Promise<void>;
  deleteUser(id: number): Promise<void>;
  settings: {
    timeout: number;
  };
}

// 仅提取方法
type UserServiceMethods = OnlyFunctions<UserService>;
// {
//   fetchUser: (id: number) => Promise<User>;
//   updateUser: (user: User) => Promise<void>;
//   deleteUser: (id: number) => Promise<void>;
// }

// 获取方法名称
type MethodNames = FunctionKeys<UserService>;
// "fetchUser" | "updateUser" | "deleteUser"

部分表单更新

import type { DeepPartial, ShapeFromPaths } from '@skyroc/type-utils';

type UserProfile = {
  personal: {
    firstName: string;
    lastName: string;
    email: string;
  };
  settings: {
    notifications: boolean;
    theme: 'light' | 'dark';
  };
};

// 允许部分更新
function updateProfile(updates: DeepPartial<UserProfile>) {
  // 可以部分更新任何嵌套属性
}

updateProfile({
  personal: {
    firstName: "John" // 仅更新 firstName
  }
});

// 或选择特定字段
type ProfilePaths = ['personal.firstName', 'personal.email', 'settings.theme'];
type UpdateableFields = ShapeFromPaths<UserProfile, ProfilePaths>;

function updateSpecificFields(updates: UpdateableFields) {
  // 仅允许更新指定的路径
}

可读的类型别名

import type { Prettify } from '@skyroc/type-utils';

// 不使用 Prettify - 难以阅读
type UserWithRole = User & { role: string } & { permissions: string[] };

// 使用 Prettify - 清晰易读
type CleanUserWithRole = Prettify<User & { role: string } & { permissions: string[] }>;
// 悬停显示: { id: number; name: string; role: string; permissions: string[] }

📖 TypeScript 支持

此包专为 TypeScript 设计，需要 TypeScript 4.7 或更高版本才能使用全部功能。所有类型都通过 JSDoc 注释完整记录，提供出色的 IDE 支持。

// 出色的自动完成和类型提示
import type {
  LeafPaths,    // ← IDE 显示完整文档
  PathToType,   // ← 包含使用示例
  DeepPartial   // ← 和类型定义
} from '@skyroc/type-utils';

📄 许可证

MIT License

🔗 链接

• GitHub 仓库
• 问题跟踪