@planet-matrix/mobius-model 0.3.0 → 0.5.0

package/src/type/class.ts

@@ -0,0 +1,419 @@
+// oxlint-disable no-explicit-any
+
+// ============================================================================
+// Primitives
+// ============================================================================
+
+/**
+ * Define a constructor type for a class.
+ *
+ * @example
+ * ```
+ * // Expect: new (name: string, age: number) => Person
+ * type Example1 = ClassConstructor<Person, [name: string, age: number]>
+ * // Expect: new () => Date
+ * type Example2 = ClassConstructor<Date>
+ * ```
+ */
+export type ClassConstructor<Instance = unknown, Args extends readonly unknown[] = []> =
+  new (...args: Args) => Instance
+
+/**
+ * Define an abstract constructor type for a class.
+ *
+ * @example
+ * ```
+ * abstract class Base {}
+ * // Expect: abstract new () => Base
+ * type Example1 = ClassAbstractConstructor<Base>
+ * ```
+ */
+export type ClassAbstractConstructor<Instance = unknown, Args extends readonly unknown[] = []> =
+  abstract new (...args: Args) => Instance
+
+/**
+ * Define a class decorator signature.
+ *
+ * @example
+ * ```
+ * class Base {}
+ * // Expect: (target: typeof Base) => typeof Base
+ * type Example1 = ClassDecorator<typeof Base>
+ * ```
+ */
+export type ClassDecorator<C extends abstract new (...args: any[]) => any> =
+  (target: C) => C
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Check if a type is a constructor.
+ *
+ * @example
+ * ```
+ * class Foo {}
+ * type Factory = () => Foo
+ * // Expect: true
+ * type Example1 = ClassIsConstructor<typeof Foo>
+ * // Expect: false
+ * type Example2 = ClassIsConstructor<Factory>
+ * ```
+ */
+export type ClassIsConstructor<T> = T extends new (...args: any[]) => any ? true : false
+
+/**
+ * Check if a type is an abstract constructor.
+ *
+ * @example
+ * ```
+ * abstract class Base {}
+ * class Concrete {}
+ * // Expect: true
+ * type Example1 = ClassIsAbstractConstructor<typeof Base>
+ * // Expect: false
+ * type Example2 = ClassIsAbstractConstructor<typeof Concrete>
+ * ```
+ */
+export type ClassIsAbstractConstructor<T> = T extends abstract new (...args: any[]) => any ? true : false
+
+/**
+ * Check if a type is a concrete (non-abstract) constructor.
+ *
+ * @example
+ * ```
+ * abstract class Base {}
+ * class Concrete {}
+ * type Factory = () => Concrete
+ * // Expect: true
+ * type Example1 = ClassIsConcreteConstructor<typeof Concrete>
+ * // Expect: false
+ * type Example2 = ClassIsConcreteConstructor<typeof Base>
+ * // Expect: false
+ * type Example3 = ClassIsConcreteConstructor<Factory>
+ * ```
+ */
+export type ClassIsConcreteConstructor<T> =
+  T extends new (...args: any[]) => any
+  ? (T extends abstract new (...args: any[]) => any ? false : true)
+  : false
+
+/**
+ * Check if a constructor has parameters.
+ *
+ * @example
+ * ```
+ * class Empty { constructor() {} }
+ * class Person { constructor(name: string) {} }
+ * // Expect: false
+ * type Example1 = ClassHasConstructorParameters<typeof Empty>
+ * // Expect: true
+ * type Example2 = ClassHasConstructorParameters<typeof Person>
+ * ```
+ */
+export type ClassHasConstructorParameters<C extends abstract new (...args: any[]) => any> =
+  ConstructorParameters<C> extends infer P extends readonly unknown[]
+  ? (P['length'] extends 0 ? false : true)
+  : false
+
+// ============================================================================
+// Comparison
+// ============================================================================
+
+/**
+ * Check if a value type is an instance of a class constructor.
+ *
+ * @example
+ * ```
+ * class Person { name = 'demo' }
+ * type Value = { name: string }
+ * // Expect: true
+ * type Example1 = ClassIsInstance<Value, typeof Person>
+ * // Expect: false
+ * type Example2 = ClassIsInstance<number, typeof Person>
+ * ```
+ */
+export type ClassIsInstance<Value, C extends abstract new (...args: any[]) => any> =
+  Value extends InstanceType<C> ? true : false
+
+/**
+ * Check if class A extends class B (structurally by instance type).
+ *
+ * @example
+ * ```
+ * class Base { id = 1 }
+ * class Derived extends Base {}
+ * // Expect: true
+ * type Example1 = ClassIsExtend<typeof Derived, typeof Base>
+ * // Expect: false
+ * type Example2 = ClassIsExtend<typeof Base, typeof Derived>
+ * ```
+ */
+export type ClassIsExtend<A extends abstract new (...args: any[]) => any, B extends abstract new (...args: any[]) => any> =
+  InstanceType<A> extends InstanceType<B> ? true : false
+
+/**
+ * Check if class C implements interface I (structurally by instance type).
+ *
+ * @example
+ * ```
+ * interface Shape { area(): number }
+ * class Square implements Shape { area() { return 1 } }
+ * // Expect: true
+ * type Example1 = ClassIsImplement<typeof Square, Shape>
+ * // Expect: false
+ * type Example2 = ClassIsImplement<typeof Square, { perimeter(): number }>
+ * ```
+ */
+export type ClassIsImplement<C extends abstract new (...args: any[]) => any, I> =
+  InstanceType<C> extends I ? true : false
+
+// ============================================================================
+// Query
+// ============================================================================
+
+/**
+ * Get constructor parameters of a class.
+ *
+ * @example
+ * ```
+ * class Person { constructor(name: string, age: number) {} }
+ * class Empty { constructor() {} }
+ * // Expect: [name: string, age: number]
+ * type Example1 = ClassConstructorParameters<typeof Person>
+ * // Expect: []
+ * type Example2 = ClassConstructorParameters<typeof Empty>
+ * ```
+ */
+export type ClassConstructorParameters<C extends abstract new (...args: any[]) => any> =
+  ConstructorParameters<C>
+
+/**
+ * Get the constructor parameter at index N.
+ *
+ * @example
+ * ```
+ * class Person { constructor(name: string, age: number) {} }
+ * // Expect: string
+ * type Example1 = ClassConstructorParameterAt<typeof Person, 0>
+ * // Expect: number
+ * type Example2 = ClassConstructorParameterAt<typeof Person, 1>
+ * // Expect: never
+ * type Example3 = ClassConstructorParameterAt<typeof Person, 2>
+ * ```
+ */
+export type ClassConstructorParameterAt<
+  C extends abstract new (...args: any[]) => any,
+  Index extends number,
+> = ConstructorParameters<C> extends infer P extends readonly unknown[]
+  ? (Index extends keyof P ? P[Index] : never)
+  : never
+
+/**
+ * Get constructor arity (parameter count).
+ *
+ * @example
+ * ```
+ * class Person { constructor(name: string, age: number) {} }
+ * class Empty { constructor() {} }
+ * // Expect: 2
+ * type Example1 = ClassConstructorArity<typeof Person>
+ * // Expect: 0
+ * type Example2 = ClassConstructorArity<typeof Empty>
+ * ```
+ */
+export type ClassConstructorArity<C extends abstract new (...args: any[]) => any> =
+  ConstructorParameters<C>['length']
+
+/**
+ * Get instance type from a class constructor.
+ *
+ * @example
+ * ```
+ * class Person { name = 'demo' }
+ * // Expect: Person
+ * type Example1 = ClassInstanceType<typeof Person>
+ * ```
+ */
+export type ClassInstanceType<C extends abstract new (...args: any[]) => any> =
+  InstanceType<C>
+
+/**
+ * Get instance type from an abstract constructor.
+ *
+ * @example
+ * ```
+ * abstract class Base { id = 1 }
+ * // Expect: Base
+ * type Example1 = ClassAbstractInstanceType<typeof Base>
+ * ```
+ */
+export type ClassAbstractInstanceType<C extends abstract new (...args: any[]) => any> =
+  InstanceType<C>
+
+type InternalInstanceRecord<C extends abstract new (...args: any[]) => any> =
+  InstanceType<C> extends infer I ? { [K in keyof I]: I[K] } : never
+/**
+ * Get all public keys on a class instance.
+ *
+ * @example
+ * ```
+ * class Person { name = 'demo'; age = 1; greet() {} }
+ * // Expect: 'name' | 'age' | 'greet'
+ * type Example1 = ClassPublicKeys<typeof Person>
+ * ```
+ */
+export type ClassPublicKeys<C extends abstract new (...args: any[]) => any> =
+  keyof InternalInstanceRecord<C>
+
+type InternalFunctionKeys<T extends Record<PropertyKey, unknown>> = {
+  [K in keyof T]-?: T[K] extends (...args: any[]) => any ? K : never
+}[keyof T]
+/**
+ * Get method keys from a class instance.
+ *
+ * @example
+ * ```
+ * class Person { name = 'demo'; greet() {} }
+ * // Expect: 'greet'
+ * type Example1 = ClassMethodKeys<typeof Person>
+ * ```
+ */
+export type ClassMethodKeys<C extends abstract new (...args: any[]) => any> =
+  InternalFunctionKeys<InternalInstanceRecord<C>>
+
+type InternalNonFunctionKeys<T extends Record<PropertyKey, unknown>> = {
+  [K in keyof T]-?: T[K] extends (...args: any[]) => any ? never : K
+}[keyof T]
+/**
+ * Get field keys (non-function) from a class instance.
+ *
+ * @example
+ * ```
+ * class Person { name = 'demo'; greet() {} }
+ * // Expect: 'name'
+ * type Example1 = ClassFieldKeys<typeof Person>
+ * ```
+ */
+export type ClassFieldKeys<C extends abstract new (...args: any[]) => any> =
+  InternalNonFunctionKeys<InternalInstanceRecord<C>>
+
+type InternalIfEquals<X, Y, TRUE = X, FALSE = never> =
+  (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? TRUE : FALSE
+type InternalReadonlyKeys<T extends Record<PropertyKey, unknown>> = {
+  [K in keyof T]-?: InternalIfEquals<{ [Q in K]: T[K] }, { -readonly [Q in K]: T[K] }, never, K>
+}[keyof T]
+/**
+ * Get readonly keys from a class instance.
+ *
+ * @example
+ * ```
+ * class Person { readonly id = 1; name = 'demo' }
+ * // Expect: 'id'
+ * type Example1 = ClassReadonlyKeys<typeof Person>
+ * ```
+ */
+export type ClassReadonlyKeys<C extends abstract new (...args: any[]) => any> =
+  InternalReadonlyKeys<InternalInstanceRecord<C>>
+
+type InternalWritableKeys<T extends Record<PropertyKey, unknown>> = {
+  [K in keyof T]-?: InternalIfEquals<{ [Q in K]: T[K] }, { -readonly [Q in K]: T[K] }, K, never>
+}[keyof T]
+/**
+ * Get writable keys from a class instance.
+ *
+ * @example
+ * ```
+ * class Person { readonly id = 1; name = 'demo' }
+ * // Expect: 'name'
+ * type Example1 = ClassWritableKeys<typeof Person>
+ * ```
+ */
+export type ClassWritableKeys<C extends abstract new (...args: any[]) => any> =
+  InternalWritableKeys<InternalInstanceRecord<C>>
+
+/**
+ * Get static keys from a class constructor.
+ *
+ * @example
+ * ```
+ * class Person { static role = 'user'; name = 'demo' }
+ * // Expect: 'prototype' | 'role'
+ * type Example1 = ClassStaticKeys<typeof Person>
+ * ```
+ */
+export type ClassStaticKeys<C extends abstract new (...args: any[]) => any> =
+  keyof C
+
+// ============================================================================
+// Extraction
+// ============================================================================
+
+/**
+ * Pick static members from a class constructor.
+ *
+ * @example
+ * ```
+ * class Person { static role = 'user'; static version = 1; name = 'demo' }
+ * // Expect: { role: string }
+ * type Example1 = ClassStaticPick<typeof Person, 'role'>
+ * ```
+ */
+export type ClassStaticPick<
+  C extends abstract new (...args: any[]) => any,
+  K extends keyof C,
+> = Pick<C, K>
+
+// ============================================================================
+// Manipulation
+// ============================================================================
+
+/**
+ * Apply a mixin to a class constructor.
+ *
+ * @example
+ * ```
+ * class Base { base = true }
+ * type Mixin = (base: typeof Base) => abstract new (...args: any[]) => Base & { extra: string }
+ * // Expect: abstract new (...args: any[]) => Base & { extra: string }
+ * type Example1 = ClassWithMixin<typeof Base, Mixin>
+ * ```
+ */
+export type ClassWithMixin<
+  C extends abstract new (...args: any[]) => any,
+  M extends (base: C) => abstract new (...args: any[]) => any,
+> = M extends (base: C) => infer Result ? Result : never
+
+/**
+ * Apply a decorator to a class constructor.
+ *
+ * @example
+ * ```
+ * class Base {}
+ * type Decorator = (target: typeof Base) => typeof Base
+ * // Expect: typeof Base
+ * type Example1 = ClassDecorate<typeof Base, Decorator>
+ * ```
+ */
+export type ClassDecorate<
+  C extends abstract new (...args: any[]) => any,
+  D extends (target: C) => C,
+> = D extends (target: C) => infer Result ? Result : never
+
+// ============================================================================
+// Conversion
+// ============================================================================
+
+/**
+ * Convert a class constructor to a regular function signature.
+ *
+ * @example
+ * ```
+ * class Person { constructor(name: string, age: number) {} }
+ * // Expect: (name: string, age: number) => Person
+ * type Example1 = ClassConstructorToFunction<typeof Person>
+ * ```
+ */
+export type ClassConstructorToFunction<C extends abstract new (...args: any[]) => any> =
+  (...args: ConstructorParameters<C>) => InstanceType<C>