@xaendar/types 0.10.7 → 0.11.0

package/dist/xaendar-types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * An abstract constructor function type that can accept any number of arguments
+ * and return an instance of the specified type.
+ */
+export declare type AbstractConstructor<T extends object = object, Statics extends Record<string, unknown> | undefined = undefined> = (abstract new (...args: any[]) => T) & (Statics extends undefined ? object : Statics);
+
+/**
+ * Represents a class accessor decorator function.
+ *
+ * Note: the `context` parameter uses `Field` (not `ReturnTypeField`) because
+ * `ClassAccessorDecoratorContext` is tied to the original field type.
+ *
+ * @template Class - The class that owns the decorated accessor.
+ * @template Value - The original type of the accessor's value.
+ * @template ActualValue - The type returned/set by the replacement accessor (defaults to `InitialValue`).
+ */
+export declare type AccessorDecorator<Class extends object, Value = unknown> = (value: ClassAccessorDecoratorValue<Value>, context: ClassAccessorDecoratorContext<Class, Value>) => {
+    /**
+     * Replacement getter returning a value of `Value`.
+     */
+    get?(this: Class): Value;
+    /**
+     * Replacement setter accepting a value of `Value`.
+     */
+    set?(this: Class, value: Value): void;
+    /**
+     * Initializer called with the original field value; should return a `Value`.
+     */
+    init?(this: Class, initialValue: Value): Value;
+} | void;
+
+/**
+ * A function type that can accept any number of arguments and return a promise of any type.
+ */
+export declare type AsyncFunction<Arguments extends any[] = any[], ReturnType = void> = Arguments extends Array<any> ? (...args: Arguments) => Promise<ReturnType> : () => Promise<ReturnType>;
+
+/**
+ * Flattens the display of an intersection or mapped type so that IDEs show
+ * the resolved property list instead of the raw intersection expression.
+ *
+ * Useful for improving hover information on complex composed types.
+ *
+ * @template T - The object type to beautify.
+ *
+ * @example
+ * type Merged = Beautify<{ a: string } & { b: number }>;
+ * // Hovering shows: { a: string; b: number }
+ */
+export declare type Beautify<T extends Object> = {
+    [K in keyof T]: T[K];
+} & {};
+
+/**
+ * Represents the accessor descriptor passed to a class accessor decorator,
+ * containing the original `get` and `set` methods of the decorated accessor.
+ *
+ * @template Field - The type of the accessor's value.
+ */
+export declare type ClassAccessorDecoratorValue<Field = unknown> = {
+    /**
+     * Returns the current value of the accessor.
+     */
+    get(this: unknown): Field;
+    /**
+     * Sets the value of the accessor.
+     */
+    set(this: unknown, value: Field): void;
+};
+
+/**
+ * Represents a TC39 stage-3 class decorator function.
+ *
+ * Receives the class constructor and its decorator context and may return a
+ * replacement constructor or `void` to leave the original unchanged.
+ *
+ * @template T - The instance type of the decorated class.
+ * @template Statics - Optional static members of the class.
+ */
+declare type ClassDecorator_2<T extends Object, Statics extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = (klass: Constructor<T, Statics>, context: ClassDecoratorContext) => void;
+export { ClassDecorator_2 as ClassDecorator }
+
+/**
+ * A constructor function type that can accept any number of arguments and return an instance of any type.
+ */
+export declare type Constructor<T extends object = object, Statics extends Record<string, unknown> | undefined = undefined> = (new (...args: any[]) => T) & (Statics extends undefined ? object : Statics);
+
+/**
+ * Recursively checks whether a string literal type contains a specific
+ * single-character substring.
+ *
+ * Resolves to `true` if `Contains` is found anywhere in `String`,
+ * or `false` if it is absent.
+ *
+ * @template String - The string literal type to inspect.
+ * @template Contains - The single character to search for.
+ *
+ * @example
+ * type HasMinus = ContainsChar<'-1', '-'>; // true
+ * type HasDot = ContainsChar<'42', '.'>; // false
+ */
+export declare type ContainsChar<String extends string, Contains extends string> = String extends `${infer First}${infer Rest}` ? First extends Contains ? true : ContainsChar<Rest, Contains> : false;
+
+/**
+ * A strongly-typed key/value map where every value is optional.
+ *
+ * Useful as a looser alternative to `Record<K, V>` when not all keys
+ * are guaranteed to be present.
+ *
+ * @template Key - The allowed key type. Must be a string or number.
+ * @template Value - The type of each value. Defaults to `string`.
+ *
+ * @example
+ * const headers: Dictionary<string, string> = { 'Content-Type': 'application/json' };
+ */
+export declare type Dictionary<Key extends string | number, Value = string> = {
+    [K in Key]?: Value;
+};
+
+/**
+ * Represents a TC39 stage-3 class field decorator function.
+ *
+ * Receives the initial `undefined` value and the field decorator context.
+ * Returns an initializer that maps the declared field value to its stored
+ * (possibly transformed) representation.
+ *
+ * @template Class - The class that owns the decorated field.
+ * @template Field - The declared type of the field.
+ * @template ReturnType - The type the initializer transforms the value into. Defaults to `Field`.
+ */
+export declare type FieldDecorator<Class extends Object, Field, ReturnType = Field> = (field: undefined, context: ClassFieldDecoratorContext<Class, Field>) => ((value: Field) => ReturnType);
+
+/**
+ * A function type that can accept any number of arguments and return any type.
+ */
+declare type Function_2<Arguments extends any[] = any[], ReturnType = void> = Arguments extends Array<any> ? (...args: Arguments) => ReturnType : () => ReturnType;
+export { Function_2 as Function }
+
+/**
+ * Represents a TC39 stage-3 class method decorator function.
+ *
+ * Receives the original method and its decorator context, and may return a
+ * replacement method or `void` to leave the original unchanged.
+ *
+ * @template T - The class that owns the decorated method.
+ * @template Method - The type of the method being decorated.
+ */
+declare type MethodDecorator_2<T extends Object, Method extends Function_2> = (value: Method, context: ClassMethodDecoratorContext<T, Method>) => Method | void;
+export { MethodDecorator_2 as MethodDecorator }
+
+/**
+ * Removes the `readonly` modifier from every property of an object type,
+ * producing a fully mutable version.
+ *
+ * The inverse of `Readonly<T>`.
+ *
+ * @template T - The object type whose properties should become mutable.
+ *
+ * @example
+ * type MutablePoint = Mutable<{ readonly x: number; readonly y: number }>;
+ * // { x: number; y: number }
+ */
+export declare type Mutable<T extends Object> = {
+    -readonly [P in keyof T]: T[P];
+};
+
+/**
+ * An async function type that accepts no arguments and returns a promise of the specified type.
+ * @template ReturnType - The type that the promise resolves to (defaults to void)
+ * @example
+ * type FetchUser = NoArgsAsyncFunction<User>;
+ * const fetchUser: FetchUser = async () => await api.getUser();
+ */
+export declare type NoArgsAsyncFunction<ReturnType = void> = () => Promise<ReturnType>;
+
+/**
+ * An async function type that accepts arguments but always resolves to void.
+ */
+export declare type NoArgsAsyncVoidFunction = () => Promise<void>;
+
+/**
+ * A function type that accepts no arguments and returns a value of the specified type.
+ * Also known as a 'thunk' in functional programming.
+ * @template ReturnType - The return type of the function (defaults to void)
+ * @example
+ * type GetUser = NoArgsFunction<User>;
+ * const getUser: GetUser = () => ({ id: 1, name: 'John' });
+ */
+export declare type NoArgsFunction<ReturnType = void> = () => ReturnType;
+
+/**
+ * A function type that accepts arguments but always returns void.
+ */
+export declare type NoArgsVoidFunction = () => void;
+
+/**
+ * Resolves to `Value` when it is a positive integer, or `never` otherwise.
+ *
+ * Rejects negative numbers (contain `'-'`) and non-integer numbers (contain `'.'`).
+ * Useful as a compile-time constraint for length or count parameters.
+ *
+ * @template Value - The numeric literal to validate.
+ *
+ * @example
+ * type Valid = PositiveInteger<5>;   // 5
+ * type Invalid = PositiveInteger<-1>; // never
+ * type Float = PositiveInteger<1.5>;  // never
+ */
+export declare type PositiveInteger<Value extends number> = ContainsChar<`${Value}`, '-'> extends true ? never : ContainsChar<`${Value}`, '.'> extends true ? never : Value;
+
+/**
+ * Creates a type from `T` where at least one of the specified `Keys` must
+ * be provided, while the remaining keys stay optional.
+ *
+ * Useful for option bags where a minimum of one field is required to avoid
+ * ambiguous or meaningless configurations.
+ *
+ * @template T - The base object type.
+ * @template Keys - The subset of keys of which at least one must be present.
+ *   Defaults to all keys of `T`.
+ *
+ * @example
+ * type SearchParams = RequireOne<{ query?: string; id?: number }>;
+ * // Valid:   { query: 'foo' }  |  { id: 42 }  |  { query: 'foo', id: 42 }
+ * // Invalid: {}  (TypeScript error)
+ */
+export declare type RequireOne<T extends Object, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+}[Keys];
+
+/**
+ * Constructs a fixed-length tuple of type `TupleType` with exactly `Length`
+ * elements.
+ *
+ * Resolves to `never` when `Length` is not a positive integer.
+ *
+ * @template Length - The number of elements. Must be a positive integer.
+ * @template TupleType - The element type. Defaults to `number`.
+ * @template Acc - Internal accumulator (do not provide manually).
+ *
+ * @example
+ * type Three = TupleOfLength<3, string>; // [string, string, string]
+ * type Bad = TupleOfLength<0, string>;   // never
+ */
+export declare type TupleOfLength<Length extends number, TupleType = number, Acc extends TupleType[] = []> = PositiveInteger<Length> extends never ? never : Acc['length'] extends Length ? Acc : TupleOfLength<Length, TupleType, [...Acc, TupleType]>;
+
+/**
+ * An async function type that accepts arguments but always resolves to void.
+ * Typically used for async callbacks or side-effect functions.
+ * @template Arguments - The types of the function arguments
+ * @example
+ * type OnUserChangeAsync = VoidAsyncFunction<[user: User]>;
+ * const handleUserChangeAsync: OnUserChangeAsync = async (user) => await api.logChange(user);
+ */
+export declare type VoidAsyncFunction<Arguments extends any[] = any[]> = (...args: Arguments) => Promise<void>;
+
+/**
+ * A function type that accepts arguments but always returns void.
+ * Typically used for callbacks, event handlers, or side-effect functions.
+ * @template Arguments - The types of the function arguments
+ * @example
+ * type OnUserChange = VoidFunction<[user: User]>;
+ * const handleUserChange: OnUserChange = (user) => console.log(user);
+ */
+declare type VoidFunction_2<Arguments extends any[] = any[]> = (...args: Arguments) => void;
+export { VoidFunction_2 as VoidFunction }
+
+export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaendar/types",
-  "version": "0.10.7",
+  "version": "0.11.0",
   "description": "A library containing common types shared across packages and consumers",
   "sideEffects": false,
   "type": "module",