@xaendar/types 0.6.14 → 0.6.15

package/dist/xaendar-types.es.d.ts

@@ -34,6 +34,18 @@ export declare type AccessorDecorator<Class extends object, Value = unknown> = (
  */
 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];
 } & {};
@@ -55,6 +67,15 @@ export declare type ClassAccessorDecoratorValue<Field = unknown> = {
     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;
 } = {
@@ -67,12 +88,49 @@ export { ClassDecorator_2 as ClassDecorator }
  */
 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);
 
 /**
@@ -81,9 +139,30 @@ export declare type FieldDecorator<Class extends Object, Field, ReturnType = Fie
 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];
 };
@@ -117,12 +196,55 @@ export declare type NoArgsFunction<ReturnType = void> = () => ReturnType;
  */
 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]>;
 
 /**

package/package.json

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