@xaendar/types 0.12.0 → 0.13.0

package/dist/xaendar-types.d.ts

@@ -2,19 +2,19 @@
  * 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);
+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) & {
+    prototype: T;
+};
 
 /**
- * Represents a class accessor decorator function.
- *
- * Note: the `context` parameter uses `Field` (not `ReturnTypeField`) because
- * `ClassAccessorDecoratorContext` is tied to the original field type.
+ * Represents a class accessor decorator function. It may return a replacement getter, setter or initializer,
+ * or `void` to leave the accessor unchanged.
  *
  * @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`).
+ * @template Value - The type of the accessor's value, the same for the original accessor and its replacement.
+ * @template Metadata - The shape of the metadata of the class (see {@link DecoratorMetadataContext}).
  */
-export declare type AccessorDecorator<Class extends object, Value = unknown> = (value: ClassAccessorDecoratorValue<Value>, context: ClassAccessorDecoratorContext<Class, Value>) => {
+export declare type AccessorDecorator<Class extends object, Value = unknown, Metadata extends object = DecoratorMetadataObject> = (value: ClassAccessorDecoratorValue<Value>, context: DecoratorMetadataContext<ClassAccessorDecoratorContext<Class, Value>, Metadata>) => {
     /**
      * Replacement getter returning a value of `Value`.
      */
@@ -70,23 +70,26 @@ export declare type ClassAccessorDecoratorValue<Field = unknown> = {
 /**
  * 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.
+ * Receives the class constructor and its decorator context, and returns `void`:
+ * the original class is left in place, it cannot be replaced.
  *
  * @template T - The instance type of the decorated class.
  * @template Statics - Optional static members of the class.
+ * @template Metadata - The shape of the metadata of the class (see {@link DecoratorMetadataContext}).
  */
 declare type ClassDecorator_2<T extends Object, Statics extends {
     [key: string]: any;
 } = {
     [key: string]: any;
-}> = (klass: Constructor<T, Statics>, context: ClassDecoratorContext) => void;
+}, Metadata extends object = DecoratorMetadataObject> = (klass: Constructor<T, Statics>, context: DecoratorMetadataContext<ClassDecoratorContext<Constructor<T, Statics>>, Metadata>) => 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);
+export declare type Constructor<T extends object = object, Statics extends Record<string, unknown> | undefined = undefined> = (new (...args: any[]) => T) & (Statics extends undefined ? object : Statics) & {
+    prototype: T;
+};
 
 /**
  * Recursively checks whether a string literal type contains a specific
@@ -104,13 +107,32 @@ export declare type Constructor<T extends object = object, Statics extends Recor
  */
 export declare type ContainsChar<String extends string, Contains extends string> = String extends `${infer First}${infer Rest}` ? First extends Contains ? true : ContainsChar<Rest, Contains> : false;
 
+/**
+ * Represents the context of a TC39 stage-3 decorator whose `metadata` has the shape the decorators of the class store in
+ * it, instead of the untyped `DecoratorMetadataObject`.
+ *
+ * The metadata is `Partial`: while the class is being decorated it holds only what the decorators applied so far
+ * stored, and the metadata of a subclass starts from the one of its parent class.
+ *
+ * @template Context - The context of the decorator, such as `ClassFieldDecoratorContext<Class, Value>`.
+ * @template Metadata - The shape of the metadata. Defaults to `DecoratorMetadataObject`.
+ */
+export declare type DecoratorMetadataContext<Context extends {
+    metadata: DecoratorMetadataObject;
+}, Metadata extends object = DecoratorMetadataObject> = Omit<Context, 'metadata'> & {
+    /**
+     * The metadata of the class being decorated.
+     */
+    metadata: Partial<Metadata>;
+};
+
 /**
  * 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 Key - The allowed key type. Must be a string, a number or a symbol.
  * @template Value - The type of each value. Defaults to `string`.
  *
  * @example
@@ -124,21 +146,34 @@ export declare type Dictionary<Key extends string | number | symbol, Value = str
  * 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.
+ * May return an initializer that maps the declared field value to its stored
+ * (possibly transformed) representation, or `void` to leave the field unchanged.
  *
  * @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`.
+ * @template Metadata - The shape of the metadata of the class (see {@link DecoratorMetadataContext}).
  */
-export declare type FieldDecorator<Class extends Object, Field, ReturnType = Field> = (field: undefined, context: ClassFieldDecoratorContext<Class, Field>) => ((value: Field) => ReturnType);
+export declare type FieldDecorator<Class extends Object, Field, ReturnType = Field, Metadata extends object = DecoratorMetadataObject> = (field: undefined, context: DecoratorMetadataContext<ClassFieldDecoratorContext<Class, Field>, Metadata>) => ((value: Field) => ReturnType) | void;
 
 /**
  * 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;
+declare type Function_2<Arguments extends any[] = any[], ReturnType = void> = (...args: Arguments) => ReturnType;
 export { Function_2 as Function }
 
+/**
+ * Represents a TC39 stage-3 class getter decorator function.
+ *
+ * Receives the original getter and its decorator context, and may return a
+ * replacement getter or `void` to leave the original unchanged.
+ *
+ * @template Class - The class that owns the decorated getter.
+ * @template Value - The type the getter returns.
+ * @template Metadata - The shape of the metadata of the class (see {@link DecoratorMetadataContext}).
+ */
+export declare type GetterDecorator<Class extends Object, Value, Metadata extends object = DecoratorMetadataObject> = (value: (this: Class) => Value, context: DecoratorMetadataContext<ClassGetterDecoratorContext<Class, Value>, Metadata>) => ((this: Class) => Value) | void;
+
 /**
  * Represents a TC39 stage-3 class method decorator function.
  *
@@ -147,8 +182,9 @@ export { Function_2 as Function }
  *
  * @template T - The class that owns the decorated method.
  * @template Method - The type of the method being decorated.
+ * @template Metadata - The shape of the metadata of the class (see {@link DecoratorMetadataContext}).
  */
-declare type MethodDecorator_2<T extends Object, Method extends Function_2> = (value: Method, context: ClassMethodDecoratorContext<T, Method>) => Method | void;
+declare type MethodDecorator_2<T extends Object, Method extends Function_2, Metadata extends object = DecoratorMetadataObject> = (value: Method, context: DecoratorMetadataContext<ClassMethodDecoratorContext<T, Method>, Metadata>) => Method | void;
 export { MethodDecorator_2 as MethodDecorator }
 
 /**
@@ -177,7 +213,7 @@ export declare type Mutable<T extends Object> = {
 export declare type NoArgsAsyncFunction<ReturnType = void> = () => Promise<ReturnType>;
 
 /**
- * An async function type that accepts arguments but always resolves to void.
+ * An async function type that takes no arguments and resolves to void.
  */
 export declare type NoArgsAsyncVoidFunction = () => Promise<void>;
 
@@ -192,7 +228,7 @@ export declare type NoArgsAsyncVoidFunction = () => Promise<void>;
 export declare type NoArgsFunction<ReturnType = void> = () => ReturnType;
 
 /**
- * A function type that accepts arguments but always returns void.
+ * A function type that takes no arguments and returns void.
  */
 export declare type NoArgsVoidFunction = () => void;
 
@@ -209,7 +245,7 @@ export declare type NoArgsVoidFunction = () => void;
  * 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;
+export declare type PositiveInteger<Value extends number> = ContainsChar<`${Value}`, '-'> extends true ? never : ContainsChar<`${Value}`, '.'> extends true ? never : Value extends 0 ? never : Value;
 
 /**
  * Creates a type from `T` where at least one of the specified `Keys` must
@@ -235,15 +271,16 @@ export declare type RequireOne<T extends Object, Keys extends keyof T = keyof T>
  * Constructs a fixed-length tuple of type `TupleType` with exactly `Length`
  * elements.
  *
- * Resolves to `never` when `Length` is not a positive integer.
+ * Resolves to `never` when `Length` is negative or not an integer, and to `[]` when it is `0` or not a literal
+ * (`number`). Lengths above 999 exceed the recursion limit of TypeScript.
  *
- * @template Length - The number of elements. Must be a positive integer.
+ * @template Length - The number of elements. Must be a non-negative integer literal.
  * @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
+ * type Empty = TupleOfLength<0, string>; // []
  */
 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.12.0",
+  "version": "0.13.0",
   "description": "A library containing common types shared across packages and consumers",
   "sideEffects": false,
   "type": "module",