@pawover/kit 0.4.2 → 0.6.0

package/packages/types/dist/index.d.cts

@@ -0,0 +1 @@
+export type * from './index.d.ts'

package/packages/types/dist/index.d.ts

@@ -0,0 +1,271 @@
+import { Split, TupleToUnion } from "type-fest";
+//#region src/advancedRecord.d.ts
+/**
+ * 高级记录模式
+ *
+ * 由必选/可选标记（`"?"` | `"!"`）与读写权限标记（`"W"` | `"R"`）组成的二元组，用于控制 `AdvancedRecord` 的字段形态。
+ *
+ * @example
+ * ```ts
+ * // 必选且可读写
+ * const mode: AdvancedRecordMode = ["!", "W"];
+ * // 可选且只读
+ * const readonlyMode: AdvancedRecordMode = ["?", "R"];
+ * ```
+ */
+type AdvancedRecordMode = ["?" | "!", "W" | "R"];
+/**
+ * 高级记录（Advanced Record）
+ *
+ * 按模式组合生成指定键集合的映射类型，可控制字段的必选/可选与只读/可写。
+ *
+ * @template K 键集合
+ * @template A 值类型
+ * @template mode 记录模式（默认必选且可读写）
+ *
+ * @example
+ * ```ts
+ * // 默认模式：必选且可读写
+ * type A = AdvancedRecord<"id" | "name", string>;
+ * // { id: string; name: string }
+ *
+ * // 可选且只读
+ * type B = AdvancedRecord<"id", string, ["?", "R"]>;
+ * // { readonly id?: string }
+ * ```
+ */
+type AdvancedRecord<K extends PropertyKey, A = unknown, mode extends AdvancedRecordMode = ["!", "W"]> = {
+  "!": {
+    R: { readonly [P in K]: A; };
+    W: { [P in K]: A; };
+  };
+  "?": {
+    R: { readonly [P in K]?: A; };
+    W: { [P in K]?: A; };
+  };
+}[mode[0]][mode[1]];
+//#endregion
+//#region src/api.d.ts
+/** 字母表 */
+type ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/** 单个字母 */
+type Letter = TupleToUnion<Split<ALPHABET, "">>;
+/** 有效字符 */
+type ValidChar = Letter | "_";
+/**
+ * API 命名检查
+ *
+ * 递归校验命名仅包含大写字母与下划线，并剥离尾随下划线；遇到非法字符时返回空字符串。
+ *
+ * @template N 待检查的命名
+ * @template P 内部递归累计结果（由编译器推导，无需传入）
+ *
+ * @returns 剥离尾随下划线后的合法命名；包含非法字符时为 `""`
+ *
+ * @example
+ * ```ts
+ * type A = ApiNameCheck<"GET_USER">; // "GET_USER"
+ * type B = ApiNameCheck<"GET_USER_">; // "GET_USER"（尾随下划线被剥离）
+ * type C = ApiNameCheck<"getUser">; // ""（小写字符非法）
+ * ```
+ */
+type ApiNameCheck<N extends string, P extends string = ""> = N extends `${infer L extends ValidChar}${infer R}` ? ApiNameCheck<R, `${P}${L}`> : P extends `${infer S}_` ? S : P;
+//#endregion
+//#region src/global.d.ts
+/**
+ * 原始类型
+ *
+ * TypeScript 中的全部原始值类型集合。
+ *
+ * @example
+ * ```ts
+ * const a: Primitive = "str";
+ * const b: Primitive = 42;
+ * const c: Primitive = null;
+ * ```
+ */
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+/**
+ * 任意对象类型
+ *
+ * 以索引签名描述任意键值对对象，键类型默认为 `PropertyKey`，值类型默认为 `any`。
+ *
+ * @template K 键类型
+ * @template T 值类型
+ *
+ * @example
+ * ```ts
+ * const obj: AnyObject = { a: 1, b: "2" };
+ * const numObj: AnyObject<"id", number> = { id: 1 };
+ * ```
+ */
+type AnyObject<K extends PropertyKey = PropertyKey, T = any> = Record<K, T>;
+/**
+ * 普通对象类型
+ *
+ * 以索引签名描述普通对象，值类型默认为 `unknown`，比 `AnyObject` 更严格。
+ *
+ * @template K 键类型
+ * @template T 值类型
+ *
+ * @example
+ * ```ts
+ * const obj: PlainObject = { a: 1 };
+ * const strMap: PlainObject<string, string> = { key: "value" };
+ * ```
+ */
+type PlainObject<K extends PropertyKey = PropertyKey, T = unknown> = Record<K, T>;
+/**
+ * 描述树类型
+ *
+ * 递归结构：每个节点都包含子树节点数组（子节点键名默认为 `children`）。
+ *
+ * @template T 节点基础类型（需为对象类型）
+ * @template CK 子节点键名
+ *
+ * @example
+ * ```ts
+ * interface Node {
+ *   id: number;
+ *   name: string;
+ * }
+ * const tree: TreeLike<Node> = {
+ *   id: 1,
+ *   name: "root",
+ *   children: [{ id: 2, name: "leaf", children: [] }],
+ * };
+ * ```
+ */
+type TreeLike<T extends AnyObject, CK extends string = "children"> = T & Record<CK, TreeLike<T, CK>[]>;
+/**
+ * 描述可选子节点树类型
+ *
+ * 递归结构：每个节点都可省略子节点键（子节点键名默认为 `children`）。
+ *
+ * @template T 节点基础类型（需为对象类型）
+ * @template CK 子节点键名
+ *
+ * @example
+ * ```ts
+ * interface Node {
+ *   id: number;
+ *   name: string;
+ * }
+ * const leaf: TreeLikeOptionalChildren<Node> = { id: 2, name: "leaf" };
+ * const root: TreeLikeOptionalChildren<Node> = {
+ *   id: 1,
+ *   name: "root",
+ *   children: [leaf],
+ * };
+ * ```
+ */
+type TreeLikeOptionalChildren<T extends AnyObject, CK extends string = "children"> = T & { [K in CK]?: TreeLikeOptionalChildren<T, CK>[]; };
+/**
+ * 描述函数类型
+ *
+ * 任意参数与任意返回值的函数类型。
+ *
+ * @template P 参数元组类型
+ * @template R 返回值类型
+ *
+ * @example
+ * ```ts
+ * const fn: AnyFunction = (a, b) => a + b;
+ * const strFn: AnyFunction<[string], string> = (s) => s.toUpperCase();
+ * ```
+ */
+type AnyFunction<P extends any[] = any[], R = any> = (...arg: P) => R;
+/**
+ * 描述异步函数类型
+ *
+ * 任意参数且返回 Promise 的函数类型。
+ *
+ * @template P 参数元组类型
+ * @template R 返回值类型
+ *
+ * @example
+ * ```ts
+ * const fn: AnyAsyncFunction = async () => {};
+ * const fetchFn: AnyAsyncFunction<[string], number> = async (url) => (await fetch(url)).status;
+ * ```
+ */
+type AnyAsyncFunction<P extends any[] = any[], R = any> = (...args: P) => Promise<R>;
+/**
+ * 描述生成器函数类型
+ *
+ * 任意参数且返回 Generator 的函数类型。
+ *
+ * @template P 参数元组类型
+ * @template T 产出值类型
+ * @template R 返回值类型
+ * @template N 下一传入值类型
+ *
+ * @example
+ * ```ts
+ * const fn: AnyGeneratorFunction<[], number> = function* () {
+ *   yield 1;
+ * };
+ * ```
+ */
+type AnyGeneratorFunction<P extends any[] = any[], T = any, R = any, N = any> = (...args: P) => Generator<T, R, N>;
+/**
+ * 描述异步生成器函数类型
+ *
+ * 任意参数且返回 AsyncGenerator 的函数类型。
+ *
+ * @template P 参数元组类型
+ * @template T 产出值类型
+ * @template R 返回值类型
+ * @template N 下一传入值类型
+ *
+ * @example
+ * ```ts
+ * const fn: AnyAsyncGeneratorFunction<[], number> = async function* () {
+ *   yield 1;
+ * };
+ * ```
+ */
+type AnyAsyncGeneratorFunction<P extends any[] = any[], T = any, R = any, N = any> = (...args: P) => AsyncGenerator<T, R, N>;
+/**
+ * 描述无返回值函数
+ *
+ * 不接受参数且返回 `void` 的函数类型。
+ *
+ * @example
+ * ```ts
+ * const fn: VoidFunction = () => {
+ *   console.log("hello");
+ * };
+ * ```
+ */
+type VoidFunction = () => void;
+/**
+ * 判断是否为原始类型
+ *
+ * 若 `T` 为原始类型则结果为 `true`，否则为 `false`。
+ *
+ * @template T 待判断的类型
+ *
+ * @example
+ * ```ts
+ * type A = IsPrimitive<string>; // true
+ * type B = IsPrimitive<{ a: 1 }>; // false
+ * ```
+ */
+type IsPrimitive<T> = T extends Primitive ? true : false;
+/**
+ * 判断是否具有索引签名
+ *
+ * 若 `T` 可被字符串索引（具有 string 索引签名）则结果为 `true`，否则为 `false`。
+ *
+ * @template T 待判断的类型
+ *
+ * @example
+ * ```ts
+ * type A = HasStringIndex<Record<string, number>>; // true
+ * type B = HasStringIndex<{ a: 1 }>; // false
+ * ```
+ */
+type HasStringIndex<T> = string extends keyof T ? true : false;
+//#endregion
+export type { AdvancedRecord, AdvancedRecordMode, AnyAsyncFunction, AnyAsyncGeneratorFunction, AnyFunction, AnyGeneratorFunction, AnyObject, ApiNameCheck, HasStringIndex, IsPrimitive, PlainObject, Primitive, TreeLike, TreeLikeOptionalChildren, VoidFunction };

package/packages/types/dist/react.d.cts

@@ -0,0 +1 @@
+export type * from './react.d.ts'

package/packages/types/dist/react.d.ts

@@ -0,0 +1,64 @@
+import { ReactNode, RefObject } from "react";
+//#region src/react.d.ts
+/**
+ * 只读 Props 类型
+ *
+ * 将任意属性集合转换为只读的组件 Props 类型。
+ *
+ * @template P 属性集合
+ *
+ * @example
+ * ```ts
+ * interface MyProps {
+ *   title: string;
+ * }
+ * const props: Props<MyProps> = { title: "hello" };
+ * // props.title = "x"; // ❌ 只读，无法修改
+ * ```
+ */
+type Props<P = unknown> = Readonly<P>;
+/**
+ * 含 children 的只读 Props 类型
+ *
+ * 在只读 Props 基础上增加可选的 `children` 属性。
+ *
+ * @template P 属性集合
+ *
+ * @example
+ * ```ts
+ * interface MyProps {
+ *   title: string;
+ * }
+ * const props: PropsWithChildren<MyProps> = {
+ *   title: "hello",
+ *   children: <span>content</span>,
+ * };
+ * ```
+ */
+type PropsWithChildren<P = unknown> = Readonly<P> & {
+  readonly children?: ReactNode | undefined;
+};
+/**
+ * 含 ref 的只读 Props 类型
+ *
+ * 在只读 Props 基础上增加可选的 `ref` 属性。
+ *
+ * @template P 属性集合
+ * @template R ref 指向的 DOM 元素类型
+ *
+ * @example
+ * ```ts
+ * interface MyProps {
+ *   title: string;
+ * }
+ * const props: PropsWithRef<MyProps, HTMLDivElement> = {
+ *   title: "hello",
+ *   ref: useRef<HTMLDivElement>(null),
+ * };
+ * ```
+ */
+type PropsWithRef<P = unknown, R = unknown> = Readonly<P> & {
+  readonly ref?: RefObject<R> | undefined;
+};
+//#endregion
+export { Props, PropsWithChildren, PropsWithRef };