strict-ts-lib-v5.2 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # strict-ts-lib-v5.2
 
+## 0.6.3
+
+### Patch Changes
+
+- 90bf42e: Two fixes to declarations that compiled fine and went wrong at the use site.
+
+    **`ReturnType<typeof setTimeout>` no longer comes out `unknown`.** `ReturnType`
+    and `InstanceType` spelled their conditional's `extends` clause
+    `(...args: readonly never[]) => infer R`. An overload set whose last member is
+    generic, with a rest parameter computed from its own type parameter, does not
+    match that — so the conditional took its false branch and produced `unknown`,
+    silently, because a false branch is a type rather than an error. `@types/node`'s
+    `setTimeout<TArgs extends any[]>(cb, ms?, ...args: MakeVoidParameterOptional<TArgs>)`
+    is exactly that shape once it merges with the DOM's `setTimeout`, so
+    `ReturnType<typeof setTimeout>` was `unknown` and could not be handed back to
+    `clearTimeout`.
+
+    The spelling is now a bare `never`, which is what the stock library itself uses
+    for `ThisParameterType` and `OmitThisParameter`, and which gives up none of the
+    `any` removal this library exists for. The type-parameter constraint is spelled
+    the same way, so the false branch is unreachable for any `T` the constraint
+    admits: "did not resolve" can no longer arrive as an `unknown` that propagates.
+
+    That `never` now has a name, `StrictLibInternals.AnyArguments`, declared in
+    `lib.es5.d.ts`. `any` reads two ways in a function type and only one of them is
+    what this library removes: `any` as a _value_ becomes `unknown` or `never` by
+    variance, while `any` as a _wildcard_ — the `(...args: any)` in `ReturnType` —
+    describes nothing at all and is there only to switch the parameter comparison
+    off. The stock library spells that wildcard two ways (`any` in `ReturnType`,
+    `never` in `ThisParameterType`); this library spells it one way, and the name
+    says which of the two readings is meant. Every such position uses it: the four
+    utility types and `ThisParameterType` in `lib.es5.d.ts`, the decorator context
+    type parameters in `lib.decorators.d.ts`, and `Reflect.construct`'s `newTarget`
+    in `lib.es2015.reflect.d.ts`. The last two were not broken; one spelling is so
+    that the trap cannot be re-dug, and so that grepping the name finds all of
+    them.
+
+    **A replacement callback's trailing arguments are `string | undefined`, not
+    `unknown`.** `String.prototype.replace` / `replaceAll` and the
+    `[Symbol.replace]` they dispatch to typed the captured groups `readonly
+unknown[]`, which forced every caller to narrow with `isString` before using a
+    group that the pattern shows can never be absent. They are now
+    `readonly (string | undefined)[]` — the type of a capture group — so contextual
+    typing gives `string | undefined` and a `?? ''` or a `!== undefined` check is
+    enough. Reading the participating-group count off a regular expression literal
+    is not something the type system can do, so this trades a little soundness for
+    it: a callback may declare a parameter past the last capture as
+    `string | undefined` and be handed the offset instead. That is still narrower
+    than the `any[]` the stock library ships.
+
 ## 0.6.2
 
 ### Patch Changes

package/libs/decorators/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference no-default-lib="true"/>
+/// <reference lib="es5" />
 
 /**
  * The decorator context types provided to class element decorators.
@@ -28,8 +29,11 @@ type DecoratorMetadata = typeof globalThis extends {
  * @template Class The type of the decorated class associated with this context.
  */
 interface ClassDecoratorContext<
-  Class extends abstract new (...args: readonly never[]) => unknown =
-    abstract new (...args: readonly never[]) => unknown,
+  Class extends abstract new (
+    ...args: StrictLibInternals.AnyArguments
+  ) => unknown = abstract new (
+    ...args: StrictLibInternals.AnyArguments
+  ) => unknown,
 > {
   /** The kind of element that was decorated. */
   readonly kind: 'class';
@@ -67,9 +71,12 @@ interface ClassDecoratorContext<
  */
 interface ClassMethodDecoratorContext<
   This = unknown,
-  Value extends (this: This, ...args: readonly never[]) => unknown = (
+  Value extends (
+    this: This,
+    ...args: StrictLibInternals.AnyArguments
+  ) => unknown = (
     this: This,
-    ...args: readonly never[]
+    ...args: StrictLibInternals.AnyArguments
   ) => unknown,
 > {
   /** The kind of class element that was decorated. */

package/libs/es2015/reflect/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference no-default-lib="true"/>
+/// <reference lib="es5" />
 
 declare namespace Reflect {
   /**
@@ -29,7 +30,7 @@ declare namespace Reflect {
   function construct<A extends readonly unknown[], R>(
     target: new (...args: A) => R,
     argumentsList: Readonly<A>,
-    newTarget?: new (...args: readonly never[]) => unknown,
+    newTarget?: new (...args: StrictLibInternals.AnyArguments) => unknown,
   ): R;
   function construct(
     target: Function,

package/libs/es2015/symbol-wellknown/index.d.ts

@@ -189,7 +189,10 @@ interface RegExp {
    */
   [Symbol.replace](
     string: string,
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 
   /**
@@ -250,10 +253,16 @@ interface String {
     searchValue: {
       [Symbol.replace](
         string: string,
-        replacer: (substring: string, ...args: readonly unknown[]) => string,
+        replacer: (
+          substring: string,
+          ...args: readonly (string | undefined)[]
+        ) => string,
       ): string;
     },
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 
   /**

package/libs/es2021/string/index.d.ts

@@ -15,6 +15,9 @@ interface String {
    */
   replaceAll(
     searchValue: string | RegExp,
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 }

package/libs/es5/index.d.ts

@@ -352,7 +352,10 @@ declare const Function: FunctionConstructor;
 /**
  * Extracts the type of the 'this' parameter of a function type, or 'unknown' if the function type has no 'this' parameter.
  */
-type ThisParameterType<T> = T extends (this: infer U, ...args: never) => unknown
+type ThisParameterType<T> = T extends (
+  this: infer U,
+  ...args: StrictLibInternals.AnyArguments
+) => unknown
   ? U
   : unknown;
 
@@ -533,7 +536,10 @@ interface String {
    */
   replace(
     searchValue: string | RegExp,
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 
   /**
@@ -1883,25 +1889,23 @@ type NonNullable<T> = T & {};
 /**
  * Obtain the parameters of a function type in a tuple
  */
-type Parameters<T extends (...args: readonly never[]) => unknown> = T extends (
-  ...args: infer P
-) => unknown
-  ? P
-  : never;
+type Parameters<
+  T extends (...args: StrictLibInternals.AnyArguments) => unknown,
+> = T extends (...args: infer P) => unknown ? P : never;
 
 /**
  * Obtain the parameters of a constructor function type in a tuple
  */
 type ConstructorParameters<
-  T extends abstract new (...args: readonly never[]) => unknown,
+  T extends abstract new (...args: StrictLibInternals.AnyArguments) => unknown,
 > = T extends abstract new (...args: infer P) => unknown ? P : never;
 
 /**
  * Obtain the return type of a function type
  */
-type ReturnType<T extends (...args: readonly never[]) => unknown> = T extends (
-  ...args: readonly never[]
-) => infer R
+type ReturnType<
+  T extends (...args: StrictLibInternals.AnyArguments) => unknown,
+> = T extends (...args: StrictLibInternals.AnyArguments) => infer R
   ? R
   : unknown;
 
@@ -1909,8 +1913,10 @@ type ReturnType<T extends (...args: readonly never[]) => unknown> = T extends (
  * Obtain the return type of a constructor function type
  */
 type InstanceType<
-  T extends abstract new (...args: readonly never[]) => unknown,
-> = T extends abstract new (...args: readonly never[]) => infer R ? R : unknown;
+  T extends abstract new (...args: StrictLibInternals.AnyArguments) => unknown,
+> = T extends abstract new (...args: StrictLibInternals.AnyArguments) => infer R
+  ? R
+  : unknown;
 
 /**
  * Convert string literal type to uppercase
@@ -5721,6 +5727,36 @@ interface Date {
   ): string;
 }
 
+declare namespace StrictLibInternals {
+  /**
+   * The rest-parameter type that means "matches any argument list". A
+   * marker rather than a type anything has: it is `never`.
+   *
+   * `any` reads two ways in a function type, and only one of them is what
+   * this library removes. `any` as a *value* — a return type, a property,
+   * an argument a caller supplies — is the unsound one, and becomes
+   * `unknown` or `never` here according to variance. `any` as a *wildcard*
+   * — the `(...args: any)` in `ReturnType` — describes nothing at all: it
+   * is there to switch the parameter comparison off, so that the
+   * conditional matches whatever signature it is handed. The stock library
+   * spells that marker two ways, `(...args: any)` in `ReturnType` and
+   * `(...args: never)` in `ThisParameterType`. This library spells it one
+   * way, and without `any`.
+   *
+   * Keep it a bare `never`. `never[]` and `readonly never[]` are ordinary
+   * array types, checked like any array: neither is assignable to a tuple
+   * with a required element, which is what the parameter list of the
+   * signature being matched turns into once that signature's own rest
+   * parameter stops being an array — as `@types/node`'s generic
+   * `setTimeout` overload does. That is what made
+   * `ReturnType<typeof setTimeout>` resolve to `unknown`, silently, a
+   * conditional's false branch being a type rather than an error.
+   *
+   * @internal
+   */
+  type AnyArguments = never;
+}
+
 type RawDateMutType = Date;
 
 type RawDateType = Readonly<RawDateMutType>;

package/libs-branded/decorators/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference no-default-lib="true"/>
+/// <reference lib="es5" />
 
 /**
  * The decorator context types provided to class element decorators.
@@ -28,8 +29,11 @@ type DecoratorMetadata = typeof globalThis extends {
  * @template Class The type of the decorated class associated with this context.
  */
 interface ClassDecoratorContext<
-  Class extends abstract new (...args: readonly never[]) => unknown =
-    abstract new (...args: readonly never[]) => unknown,
+  Class extends abstract new (
+    ...args: StrictLibInternals.AnyArguments
+  ) => unknown = abstract new (
+    ...args: StrictLibInternals.AnyArguments
+  ) => unknown,
 > {
   /** The kind of element that was decorated. */
   readonly kind: 'class';
@@ -67,9 +71,12 @@ interface ClassDecoratorContext<
  */
 interface ClassMethodDecoratorContext<
   This = unknown,
-  Value extends (this: This, ...args: readonly never[]) => unknown = (
+  Value extends (
+    this: This,
+    ...args: StrictLibInternals.AnyArguments
+  ) => unknown = (
     this: This,
-    ...args: readonly never[]
+    ...args: StrictLibInternals.AnyArguments
   ) => unknown,
 > {
   /** The kind of class element that was decorated. */

package/libs-branded/es2015/reflect/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference no-default-lib="true"/>
+/// <reference lib="es5" />
 
 declare namespace Reflect {
   /**
@@ -29,7 +30,7 @@ declare namespace Reflect {
   function construct<A extends readonly unknown[], R>(
     target: new (...args: A) => R,
     argumentsList: Readonly<A>,
-    newTarget?: new (...args: readonly never[]) => unknown,
+    newTarget?: new (...args: StrictLibInternals.AnyArguments) => unknown,
   ): R;
   function construct(
     target: Function,

package/libs-branded/es2015/symbol-wellknown/index.d.ts

@@ -189,7 +189,10 @@ interface RegExp {
    */
   [Symbol.replace](
     string: string,
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 
   /**
@@ -253,10 +256,16 @@ interface String {
     searchValue: {
       [Symbol.replace](
         string: string,
-        replacer: (substring: string, ...args: readonly unknown[]) => string,
+        replacer: (
+          substring: string,
+          ...args: readonly (string | undefined)[]
+        ) => string,
       ): string;
     },
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 
   /**

package/libs-branded/es2021/string/index.d.ts

@@ -15,6 +15,9 @@ interface String {
    */
   replaceAll(
     searchValue: string | RegExp,
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 }

package/libs-branded/es5/index.d.ts

@@ -354,7 +354,10 @@ declare const Function: FunctionConstructor;
 /**
  * Extracts the type of the 'this' parameter of a function type, or 'unknown' if the function type has no 'this' parameter.
  */
-type ThisParameterType<T> = T extends (this: infer U, ...args: never) => unknown
+type ThisParameterType<T> = T extends (
+  this: infer U,
+  ...args: StrictLibInternals.AnyArguments
+) => unknown
   ? U
   : unknown;
 
@@ -541,7 +544,10 @@ interface String {
    */
   replace(
     searchValue: string | RegExp,
-    replacer: (substring: string, ...args: readonly unknown[]) => string,
+    replacer: (
+      substring: string,
+      ...args: readonly (string | undefined)[]
+    ) => string,
   ): string;
 
   /**
@@ -2038,25 +2044,23 @@ type NonNullable<T> = T & {};
 /**
  * Obtain the parameters of a function type in a tuple
  */
-type Parameters<T extends (...args: readonly never[]) => unknown> = T extends (
-  ...args: infer P
-) => unknown
-  ? P
-  : never;
+type Parameters<
+  T extends (...args: StrictLibInternals.AnyArguments) => unknown,
+> = T extends (...args: infer P) => unknown ? P : never;
 
 /**
  * Obtain the parameters of a constructor function type in a tuple
  */
 type ConstructorParameters<
-  T extends abstract new (...args: readonly never[]) => unknown,
+  T extends abstract new (...args: StrictLibInternals.AnyArguments) => unknown,
 > = T extends abstract new (...args: infer P) => unknown ? P : never;
 
 /**
  * Obtain the return type of a function type
  */
-type ReturnType<T extends (...args: readonly never[]) => unknown> = T extends (
-  ...args: readonly never[]
-) => infer R
+type ReturnType<
+  T extends (...args: StrictLibInternals.AnyArguments) => unknown,
+> = T extends (...args: StrictLibInternals.AnyArguments) => infer R
   ? R
   : unknown;
 
@@ -2064,8 +2068,10 @@ type ReturnType<T extends (...args: readonly never[]) => unknown> = T extends (
  * Obtain the return type of a constructor function type
  */
 type InstanceType<
-  T extends abstract new (...args: readonly never[]) => unknown,
-> = T extends abstract new (...args: readonly never[]) => infer R ? R : unknown;
+  T extends abstract new (...args: StrictLibInternals.AnyArguments) => unknown,
+> = T extends abstract new (...args: StrictLibInternals.AnyArguments) => infer R
+  ? R
+  : unknown;
 
 /**
  * Convert string literal type to uppercase
@@ -6346,6 +6352,36 @@ interface Date {
   ): string;
 }
 
+declare namespace StrictLibInternals {
+  /**
+   * The rest-parameter type that means "matches any argument list". A
+   * marker rather than a type anything has: it is `never`.
+   *
+   * `any` reads two ways in a function type, and only one of them is what
+   * this library removes. `any` as a *value* — a return type, a property,
+   * an argument a caller supplies — is the unsound one, and becomes
+   * `unknown` or `never` here according to variance. `any` as a *wildcard*
+   * — the `(...args: any)` in `ReturnType` — describes nothing at all: it
+   * is there to switch the parameter comparison off, so that the
+   * conditional matches whatever signature it is handed. The stock library
+   * spells that marker two ways, `(...args: any)` in `ReturnType` and
+   * `(...args: never)` in `ThisParameterType`. This library spells it one
+   * way, and without `any`.
+   *
+   * Keep it a bare `never`. `never[]` and `readonly never[]` are ordinary
+   * array types, checked like any array: neither is assignable to a tuple
+   * with a required element, which is what the parameter list of the
+   * signature being matched turns into once that signature's own rest
+   * parameter stops being an array — as `@types/node`'s generic
+   * `setTimeout` overload does. That is what made
+   * `ReturnType<typeof setTimeout>` resolve to `unknown`, silently, a
+   * conditional's false branch being a type rather than an error.
+   *
+   * @internal
+   */
+  type AnyArguments = never;
+}
+
 type RawDateMutType = Date;
 
 type RawDateType = Readonly<RawDateMutType>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strict-ts-lib-v5.2",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "private": false,
   "description": "Strict TypeScript 5.2.2 standard library (all libs in one package)",
   "license": "Apache-2.0",