uni-types 1.0.0-beta.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 saqqdy <saqqdy@qq.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+<div style="text-align: center;" align="center">
+
+# uni-types
+
+Universal TypeScript type utilities - A comprehensive collection of type helpers for TypeScript development
+
+English | [简体中文](./README_CN.md)
+
+[![NPM version][npm-image]][npm-url]
+![typescript][typescript-url]
+[![Test coverage][codecov-image]][codecov-url]
+[![npm download][download-image]][download-url]
+[![License][license-image]][license-url]
+
+</div>
+
+## Installation
+
+```bash
+# use pnpm
+$ pnpm add uni-types
+
+# use yarn
+$ yarn add uni-types
+
+# use npm
+$ npm install uni-types
+```
+
+## Usage
+
+```typescript
+import type { PickRequired, DeepPartial, IsArray } from 'uni-types'
+
+// Use in your TypeScript projects
+interface User {
+  name?: string
+  age?: number
+  email: string
+}
+
+type RequiredNameUser = PickRequired<User, 'name'>
+// { name: string; age?: number; email: string }
+```
+
+## API Reference
+
+### Core Operations
+
+| Type | Description |
+|------|-------------|
+| `PickRequired<T, K>` | Make specified properties required |
+| `OmitRequired<T, K>` | Make properties except specified ones required |
+| `PickPartial<T, K>` | Make specified properties optional |
+| `OmitPartial<T, K>` | Make properties except specified ones optional |
+
+```typescript
+interface User {
+  name?: string
+  age?: number
+  email: string
+}
+
+PickRequired<User, 'name'>   // { name: string; age?: number; email: string }
+OmitRequired<User, 'name'>   // { name?: string; age: number; email: string }
+PickPartial<User, 'email'>   // { name?: string; age?: number; email?: string }
+OmitPartial<User, 'email'>   // { name: string; age: number; email?: string }
+```
+
+### Tuple Operations
+
+| Type | Description |
+|------|-------------|
+| `Head<T>` | Get first element of tuple |
+| `Last<T>` | Get last element of tuple |
+| `Tail<T>` | Get all elements except first |
+| `Init<T>` | Get all elements except last |
+| `Reverse<T>` | Reverse a tuple |
+| `Flatten<T>` | Flatten nested tuples |
+| `TupleLength<T>` | Get tuple length |
+| `IsEmptyTuple<T>` | Check if tuple is empty |
+
+```typescript
+Head<[1, 2, 3]>       // 1
+Last<[1, 2, 3]>       // 3
+Tail<[1, 2, 3]>       // [2, 3]
+Init<[1, 2, 3]>       // [1, 2]
+Reverse<[1, 2, 3]>    // [3, 2, 1]
+Flatten<[1, [2, [3]]]> // [1, 2, 3]
+TupleLength<[1, 2, 3]> // 3
+IsEmptyTuple<[]>       // true
+```
+
+### Deep Operations
+
+| Type | Description |
+|------|-------------|
+| `DeepPartial<T>` | Make all nested properties optional |
+| `DeepRequired<T>` | Make all nested properties required |
+| `DeepReadonly<T>` | Make all nested properties readonly |
+| `DeepMutable<T>` | Make all nested properties mutable |
+
+```typescript
+interface Nested {
+  a: { b: { c: string } }
+}
+
+DeepPartial<Nested>  // { a?: { b?: { c?: string } } }
+DeepRequired<{ a?: { b?: string } }>  // { a: { b: string } }
+DeepReadonly<Nested>  // { readonly a: { readonly b: { readonly c: string } } }
+DeepMutable<{ readonly a: { readonly b: string } }>  // { a: { b: string } }
+```
+
+### Type Guards
+
+| Type | Description |
+|------|-------------|
+| `IsArray<T>` | Check if type is an array |
+| `IsTuple<T>` | Check if type is a tuple |
+| `IsEqual<X, Y>` | Check if two types are equal |
+| `IsAny<T>` | Check if type is `any` |
+| `IsNever<T>` | Check if type is `never` |
+| `IsUnknown<T>` | Check if type is `unknown` |
+
+```typescript
+IsArray<string[]>    // true
+IsArray<string>      // false
+IsTuple<[string, number]>  // true
+IsTuple<string[]>    // false
+IsEqual<string, string>    // true
+IsEqual<string, number>    // false
+```
+
+### Type Inference
+
+| Type | Description |
+|------|-------------|
+| `Awaited<T>` | Unwrap Promise type recursively |
+| `ArrayElement<T>` | Get array element type |
+| `ValueOf<T>` | Get object value types |
+| `FunctionKeys<T>` | Get keys of function properties |
+| `NonFunctionKeys<T>` | Get keys of non-function properties |
+| `FirstParameter<T>` | Get first parameter type of function |
+
+```typescript
+Awaited<Promise<string>>           // string
+Awaited<Promise<Promise<number>>>  // number
+ArrayElement<string[]>             // string
+ValueOf<{ a: string; b: number }>  // string | number
+FunctionKeys<{ name: string; onClick: () => void }>  // 'onClick'
+NonFunctionKeys<{ name: string; onClick: () => void }>  // 'name'
+```
+
+### Utility Types
+
+| Type | Description |
+|------|-------------|
+| `Merge<T, U>` | Merge two types (U overrides T) |
+| `NonNullable<T>` | Exclude `null` and `undefined` |
+| `Exclusive<T, K>` | Create mutually exclusive properties |
+| `NoNullish<T>` | Remove null/undefined from all properties |
+| `Nullable<T>` | Add `null` to type |
+| `Optional<T>` | Add `undefined` to type |
+| `Maybe<T>` | Add `null` and `undefined` to type |
+| `LoosePartial<T>` | Make all properties optional |
+
+```typescript
+Merge<{ a: string; b: number }, { b: boolean; c: string }>
+// { a: string; b: boolean; c: string }
+
+NonNullable<string | null | undefined>  // string
+Nullable<string>   // string | null
+Optional<string>   // string | undefined
+Maybe<string>      // string | null | undefined
+```
+
+### Key Types
+
+| Type | Description |
+|------|-------------|
+| `RequiredKeys<T>` | Get all required property keys |
+| `OptionalKeys<T>` | Get all optional property keys |
+| `WritableKeys<T>` | Get all writable (non-readonly) keys |
+| `ReadonlyKeys<T>` | Get all readonly keys |
+
+```typescript
+interface User {
+  name: string
+  age?: number
+  readonly id: number
+}
+
+RequiredKeys<User>   // 'name'
+OptionalKeys<User>   // 'age'
+WritableKeys<User>   // 'name' | 'age'
+ReadonlyKeys<User>   // 'id'
+```
+
+### Path Types
+
+| Type | Description |
+|------|-------------|
+| `Paths<T>` | Get all nested property paths |
+| `PathValue<T, P>` | Get value type at path |
+| `SplitPath<S>` | Split path string into array |
+
+```typescript
+interface Obj {
+  a: { b: { c: string } }
+}
+
+Paths<Obj>                    // 'a' | 'a.b' | 'a.b.c'
+PathValue<Obj, 'a.b'>         // { c: string }
+SplitPath<'a.b.c'>            // ['a', 'b', 'c']
+```
+
+### Literal Types
+
+| Type | Description |
+|------|-------------|
+| `Literal` | All literal types union |
+| `LiteralString<T>` | Exact string literal |
+| `LiteralNumber<T>` | Exact number literal |
+| `LiteralBoolean<T>` | Exact boolean literal |
+
+```typescript
+Literal  // string | number | boolean | undefined | null | void | bigint
+LiteralString<'hello'>  // 'hello'
+LiteralNumber<42>       // 42
+LiteralBoolean<true>    // true
+```
+
+### String Case Conversion
+
+| Type | Description |
+|------|-------------|
+| `CamelCase<S>` | Convert to camelCase |
+| `SnakeCase<S>` | Convert to snake_case |
+| `CamelCaseKeys<T>` | Convert object keys to camelCase |
+| `SnakeCaseKeys<T>` | Convert object keys to snake_case |
+
+```typescript
+CamelCase<'hello_world'>    // 'helloWorld'
+CamelCase<'foo-bar-baz'>    // 'fooBarBaz'
+SnakeCase<'helloWorld'>     // 'hello_world'
+SnakeCase<'XMLParser'>      // 'xml_parser'
+CamelCaseKeys<{ hello_world: string }>  // { helloWorld: string }
+```
+
+### Advanced Types
+
+| Type | Description |
+|------|-------------|
+| `FunctionOnly<T>` | Extract only function properties |
+| `DataOnly<T>` | Extract only non-function properties |
+| `AtLeastOne<T>` | Require at least one property |
+| `StrictExtract<T, U>` | Strictly extract matching types |
+| `StrictExclude<T, U>` | Strictly exclude types |
+| `UnionToIntersection<U>` | Convert union to intersection |
+| `UnionToTuple<T>` | Convert union to tuple |
+
+```typescript
+interface Obj { name: string; onClick: () => void }
+FunctionOnly<Obj>  // { onClick: () => void }
+DataOnly<Obj>      // { name: string }
+
+UnionToIntersection<{ a: string } | { b: number }>  // { a: string } & { b: number }
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Test
+pnpm test
+
+# Test with coverage
+pnpm test:coverage
+
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
+```
+
+## License
+
+[MIT](LICENSE)
+
+[npm-image]: https://img.shields.io/npm/v/uni-types.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/uni-types
+[typescript-url]: https://badgen.net/badge/icon/typescript?icon=typescript&label
+[codecov-image]: https://img.shields.io/codecov/c/github/saqqdy/uni-types.svg?style=flat-square
+[codecov-url]: https://codecov.io/github/saqqdy/uni-types?branch=master
+[download-image]: https://img.shields.io/npm/dm/uni-types.svg?style=flat-square
+[download-url]: https://npmjs.org/package/uni-types
+[license-image]: https://img.shields.io/badge/License-MIT-blue.svg
+[license-url]: LICENSE