@eslint-react/ast 5.16.1 → 5.17.0

package/dist/index.d.ts

@@ -38,10 +38,10 @@ declare namespace compare_d_exports {
   export { isEqual };
 }
 /**
- * Check if two nodes are equal
- * @param a node to compare
- * @param b node to compare
- * @returns `true` if node equal
+ * Check if two nodes are equal.
+ * @param a node to compare.
+ * @param b node to compare.
+ * @returns `true` if node equal.
  * @see https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/util/isNodeEqual.ts
  */
 declare const isEqual: {

package/dist/index.js

@@ -121,28 +121,124 @@ const isExpression = isOneOf([
 //#endregion
 //#region ../../.pkgs/eff/dist/index.js
 /**
-* Creates a function that can be used in a data-last (aka `pipe`able) or
-* data-first style.
+* Applies a `pipe` method's variadic arguments to an initial value from left
+* to right.
 *
-* The first parameter to `dual` is either the arity of the uncurried function
-* or a predicate that determines if the function is being used in a data-first
-* or data-last style.
+* **When to use**
 *
-* Using the arity is the most common use case, but there are some cases where
-* you may want to use a predicate. For example, if you have a function that
-* takes an optional argument, you can use a predicate to determine if the
-* function is being used in a data-first or data-last style.
+* Use to implement a custom `.pipe(...)` method from JavaScript's `arguments`
+* object.
 *
-* You can pass either the arity of the uncurried function or a predicate
-* which determines if the function is being used in a data-first or
-* data-last style.
+* **Details**
 *
-* **Example** (Using arity to determine data-first or data-last style)
+* This helper is intended for implementing `Pipeable.pipe` methods that
+* receive JavaScript's `arguments` object. With no functions it returns the
+* original value; otherwise it feeds each result into the next function.
+*
+* **Example** (Implementing a pipe method)
 *
 * ```ts
-* import { dual, pipe } from "effect/Function"
+* import { Pipeable } from "effect"
+*
+* class NumberBox {
+*   constructor(readonly value: number) {}
+*
+*   pipe(..._fns: ReadonlyArray<(value: number) => number>): number {
+*     return Pipeable.pipeArguments(this.value, arguments) as number
+*   }
+* }
+*
+* const result = new NumberBox(5).pipe(
+*   (n) => n + 2,
+*   (n) => n * 3
+* )
+* console.log(result) // 21
+* ```
+*
+* @category combinators
+* @since 2.0.0
+*/
+const pipeArguments = (self, args) => {
+	switch (args.length) {
+		case 0: return self;
+		case 1: return args[0](self);
+		case 2: return args[1](args[0](self));
+		case 3: return args[2](args[1](args[0](self)));
+		case 4: return args[3](args[2](args[1](args[0](self))));
+		case 5: return args[4](args[3](args[2](args[1](args[0](self)))));
+		case 6: return args[5](args[4](args[3](args[2](args[1](args[0](self))))));
+		case 7: return args[6](args[5](args[4](args[3](args[2](args[1](args[0](self)))))));
+		case 8: return args[7](args[6](args[5](args[4](args[3](args[2](args[1](args[0](self))))))));
+		case 9: return args[8](args[7](args[6](args[5](args[4](args[3](args[2](args[1](args[0](self)))))))));
+		default: {
+			let ret = self;
+			for (let i = 0, len = args.length; i < len; i++) ret = args[i](ret);
+			return ret;
+		}
+	}
+};
+/**
+* Reusable prototype that implements `Pipeable.pipe`.
+*
+* **When to use**
+*
+* Use when classes or object prototypes can reuse this value when they need the
+* standard pipe implementation backed by `pipeArguments`.
+*
+* @category prototypes
+* @since 3.15.0
+*/
+const Prototype = { pipe() {
+	return pipeArguments(this, arguments);
+} };
+/**
+* Provides a base constructor whose instances implement the standard `Pipeable.pipe`
+* method.
+*
+* **When to use**
 *
-* const sum = dual<
+* Use when you need to define a class that supports Effect-style method
+* chaining through `.pipe(...)`.
+*
+* @category constructors
+* @since 3.15.0
+*/
+const Class = (function() {
+	function PipeableBase() {}
+	PipeableBase.prototype = Prototype;
+	return PipeableBase;
+})();
+/**
+* Provides small helpers for defining and reusing TypeScript functions.
+*
+* The main helpers are `pipe` and `flow` for left-to-right composition and
+* `dual` for APIs that support both direct and pipe-friendly call styles. The
+* module also contains small identity, constant, tuple, type-level, and
+* memoization helpers used across the library.
+*
+* @since 2.0.0
+*/
+/**
+* Creates a function that can be called in data-first style or data-last
+* (`pipe`-friendly) style.
+*
+* **When to use**
+*
+* Use to expose one implementation through both direct and `pipe`-friendly
+* call styles.
+*
+* **Details**
+*
+* Pass either the arity of the uncurried function or a predicate that decides
+* whether the current call is data-first. Arity is the common case. Use a
+* predicate when optional arguments make arity ambiguous.
+*
+* **Example** (Selecting data-first or data-last style by arity)
+*
+* ```ts
+* import { Function, pipe } from "effect"
+*
+* const sum = Function.dual<
 *   (that: number) => (self: number) => number,
 *   (self: number, that: number) => number
 * >(2, (self, that) => self + that)
@@ -151,26 +247,26 @@ const isExpression = isOneOf([
 * console.log(pipe(2, sum(3))) // 5
 * ```
 *
-* **Example** (Using call signatures to define the overloads)
+* **Example** (Defining overloads with call signatures)
 *
 * ```ts
-* import { dual, pipe } from "effect/Function"
+* import { Function, pipe } from "effect"
 *
 * const sum: {
 *   (that: number): (self: number) => number
 *   (self: number, that: number): number
-* } = dual(2, (self: number, that: number): number => self + that)
+* } = Function.dual(2, (self: number, that: number): number => self + that)
 *
 * console.log(sum(2, 3)) // 5
 * console.log(pipe(2, sum(3))) // 5
 * ```
 *
-* **Example** (Using a predicate to determine data-first or data-last style)
+* **Example** (Selecting data-first or data-last style with a predicate)
 *
 * ```ts
-* import { dual, pipe } from "effect/Function"
+* import { Function, pipe } from "effect"
 *
-* const sum = dual<
+* const sum = Function.dual<
 *   (that: number) => (self: number) => number,
 *   (self: number, that: number) => number
 * >(
@@ -182,9 +278,8 @@ const isExpression = isOneOf([
 * console.log(pipe(2, sum(3))) // 5
 * ```
 *
-* @param arity - The arity of the uncurried function or a predicate that determines if the function is being used in a data-first or data-last style.
-* @param body - The function to be curried.
-* @since 1.0.0
+* @category combinators
+* @since 2.0.0
 */
 const dual = function(arity, body) {
 	if (typeof arity === "function") return function() {
@@ -215,26 +310,235 @@ const dual = function(arity, body) {
 	}
 };
 /**
+* Returns its input argument unchanged.
+*
+* **When to use**
+*
+* Use to return a value unchanged where a function is required.
+*
+* **Example** (Returning the same value)
+*
+* ```ts
+* import { identity } from "effect"
+* import * as assert from "node:assert"
+*
+* assert.deepStrictEqual(identity(5), 5)
+* ```
+*
+* @category combinators
+* @since 2.0.0
+*/
+const identity = (a) => a;
+/**
+* Returns the input value with a different static type.
+*
+* **When to use**
+*
+* Use when you need an explicit type-level cast and accept that the value is
+* returned unchanged at runtime.
+*
+* **Gotchas**
+*
+* This is a type-level cast only; it performs no runtime validation or
+* conversion.
+*
+* @see {@link satisfies} for checking assignability without changing the resulting type
+*
+* @category utility types
+* @since 4.0.0
+*/
+const cast = identity;
+/**
+* Creates a zero-argument function that always returns the provided value.
+*
+* **When to use**
+*
+* Use when you need a thunk or callback that returns the same value on every
+* invocation.
+*
+* **Example** (Creating a constant thunk)
+*
+* ```ts
+* import { Function } from "effect"
+* import * as assert from "node:assert"
+*
+* const constNull = Function.constant(null)
+*
+* assert.deepStrictEqual(constNull(), null)
+* assert.deepStrictEqual(constNull(), null)
+* ```
+*
+* @category constructors
+* @since 2.0.0
+*/
+const constant = (value) => () => value;
+/**
+* Returns `true` when called.
+*
+* **When to use**
+*
+* Use when you need a thunk that returns `true` on every invocation.
+*
+* **Example** (Returning true from a thunk)
+*
+* ```ts
+* import { Function } from "effect"
+* import * as assert from "node:assert"
+*
+* assert.deepStrictEqual(Function.constTrue(), true)
+* ```
+*
+* @category constants
+* @since 2.0.0
+*/
+const constTrue = constant(true);
+/**
+* Returns `false` when called.
+*
+* **When to use**
+*
+* Use when you need a thunk that returns `false` on every invocation.
+*
+* **Example** (Returning false from a thunk)
+*
+* ```ts
+* import { Function } from "effect"
+* import * as assert from "node:assert"
+*
+* assert.deepStrictEqual(Function.constFalse(), false)
+* ```
+*
+* @category constants
+* @since 2.0.0
+*/
+const constFalse = constant(false);
+/**
+* Returns `null` when called.
+*
+* **When to use**
+*
+* Use when you need a thunk that returns `null` on every invocation.
+*
+* **Example** (Returning null from a thunk)
+*
+* ```ts
+* import { Function } from "effect"
+* import * as assert from "node:assert"
+*
+* assert.deepStrictEqual(Function.constNull(), null)
+* ```
+*
+* @category constants
+* @since 2.0.0
+*/
+const constNull = constant(null);
+/**
+* Returns `undefined` when called.
+*
+* **When to use**
+*
+* Use when you need a thunk that returns `undefined` on every invocation.
+*
+* **Example** (Returning undefined from a thunk)
+*
+* ```ts
+* import { Function } from "effect"
+* import * as assert from "node:assert"
+*
+* assert.deepStrictEqual(Function.constUndefined(), undefined)
+* ```
+*
+* @category constants
+* @since 2.0.0
+*/
+const constUndefined = constant(void 0);
+/**
 * Composes two functions, `ab` and `bc` into a single function that takes in an argument `a` of type `A` and returns a result of type `C`.
 * The result is obtained by first applying the `ab` function to `a` and then applying the `bc` function to the result of `ab`.
 *
-* @param self - The first function to apply (or the composed function in data-last style).
-* @param bc - The second function to apply.
-* @returns A composed function that applies both functions in sequence.
-* @example
+* **When to use**
+*
+* Use to compose exactly two unary functions into a reusable unary function.
+*
+* **Example** (Composing two functions)
+*
 * ```ts
+* import { Function } from "effect"
 * import * as assert from "node:assert"
-* import { compose } from "effect/Function"
 *
-* const increment = (n: number) => n + 1;
-* const square = (n: number) => n * n;
+* const increment = (n: number) => n + 1
+* const square = (n: number) => n * n
 *
-* assert.strictEqual(compose(increment, square)(2), 9);
+* assert.strictEqual(Function.compose(increment, square)(2), 9)
 * ```
 *
-* @since 1.0.0
+* @see {@link flow} for composing a left-to-right sequence of functions
+* @see {@link pipe} for applying a value through a left-to-right sequence immediately
+*
+* @category combinators
+* @since 2.0.0
 */
 const compose = dual(2, (ab, bc) => (a) => bc(ab(a)));
+/**
+* Marks an impossible branch by accepting a `never` value and returning any
+* type.
+*
+* **When to use**
+*
+* Use when you need a return value in a branch that exhaustive checks prove
+* cannot be reached.
+*
+* **Gotchas**
+*
+* Calling `absurd` throws, because a value of type `never` should be
+* impossible at runtime.
+*
+* **Example** (Handling impossible values)
+*
+* ```ts
+* import { absurd } from "effect"
+*
+* const handleNever = (value: never) => {
+*   return absurd(value) // This will throw an error if called
+* }
+* ```
+*
+* @category utility types
+* @since 2.0.0
+*/
+const absurd = (_) => {
+	throw new Error("Called `absurd` function which should be uncallable");
+};
+/**
+* Creates a compile-time placeholder for a value of any type.
+*
+* **When to use**
+*
+* Use as a temporary typed placeholder while developing incomplete code.
+*
+* **Gotchas**
+*
+* `hole` is intended for temporary development use. If the placeholder is
+* evaluated at runtime, it throws.
+*
+* **Example** (Creating a development placeholder)
+*
+* ```ts
+* import { hole } from "effect"
+*
+* // Intentionally not called: `hole` throws if the placeholder is evaluated.
+* const buildUser = (id: number): { readonly id: number; readonly name: string } => ({
+*   id,
+*   name: hole<string>()
+* })
+*
+* console.log(typeof buildUser) // "function"
+* ```
+*
+* @category utility types
+* @since 2.0.0
+*/
+const hole = cast(absurd);
 
 //#endregion
 //#region src/extract.ts
@@ -289,10 +593,10 @@ function getFullyQualifiedName(node, getText) {
 //#region src/compare.ts
 var compare_exports = /* @__PURE__ */ __exportAll({ isEqual: () => isEqual });
 /**
-* Check if two nodes are equal
-* @param a node to compare
-* @param b node to compare
-* @returns `true` if node equal
+* Check if two nodes are equal.
+* @param a node to compare.
+* @param b node to compare.
+* @returns `true` if node equal.
 * @see https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/util/isNodeEqual.ts
 */
 const isEqual = dual(2, (a, b) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eslint-react/ast",
-  "version": "5.16.1",
+  "version": "5.17.0",
   "description": "ESLint React's TSESTree AST utility module.",
   "homepage": "https://github.com/Rel1cx/eslint-react",
   "bugs": {