feat(flip): implement flip

benchmarks/performance/flip.bench.ts

@@ -0,0 +1,18 @@
+import { bench, describe } from 'vitest';
+import { flip as flipToolkit } from 'es-toolkit/compat';
+import { flip as flipLodash } from 'lodash';
+
+describe('flip', () => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  function fn(a: any, b: any, c: any, d: any) {
+    return [a, b, c, d];
+  }
+
+  bench('es-toolkit/flip', () => {
+    flipToolkit(fn);
+  });
+
+  bench('lodash/flip', () => {
+    flipLodash(fn);
+  });
+});

docs/reference/compat/function/flip.md

@@ -0,0 +1,40 @@
+# flip
+
+::: info
+This function is only available in `es-toolkit/compat` for compatibility reasons. It either has alternative native JavaScript APIs or isn’t fully optimized yet.
+
+When imported from `es-toolkit/compat`, it behaves exactly like lodash and provides the same functionalities, as detailed [here](../../../compatibility.md).
+:::
+
+Creates a function that invokes `func` with arguments reversed.
+
+## Signature
+
+```typescript
+type ReverseParameters<T extends any[]> = T extends [infer First, ...infer Rest]
+  ? [...ReverseParameters<Rest>, First]
+  : [];
+
+function flip<F extends (...args: any[]) => any>(func: F): (...args: ReverseParameters<Parameters<F>>) => ReturnType<F>;
+```
+
+### Parameters
+
+- `func` (`F`): The function to flip arguments for.
+
+### Returns
+
+(`(...args: ReverseParameters<Parameters<F>>) => ReturnType<F>`): The new flipped function.
+
+## Example
+
+```typescript
+import { flip } from 'es-toolkit/compat';
+
+function fn(a: any, b: any, c: any, d: any) {
+  return [a, b, c, d];
+}
+
+const flipped = flip(fn);
+flipped(1, 2, 3, 4); // => [4, 3, 2, 1]
+```

docs/zh_hans/reference/compat/function/flip.md

@@ -0,0 +1,41 @@
+# flip
+
+::: info
+出于兼容性原因，此函数仅在 `es-toolkit/compat` 中提供。它可能具有替代的原生 JavaScript API，或者尚未完全优化。
+
+从 `es-toolkit/compat` 导入时，它的行为与 lodash 完全一致，并提供相同的功能，详情请见 [这里](../../../compatibility.md)。
+
+:::
+
+创建一个函数，该函数调用 `func` 上的方法，并将参数反转。
+
+## 签名
+
+```typescript
+type ReverseParameters<T extends any[]> = T extends [infer First, ...infer Rest]
+  ? [...ReverseParameters<Rest>, First]
+  : [];
+
+function flip<F extends (...args: any[]) => any>(func: F): (...args: ReverseParameters<Parameters<F>>) => ReturnType<F>;
+```
+
+### 参数
+
+- `func` (`F`): 需要反转参数的函数。
+
+### 返回值
+
+(`(...args: ReverseParameters<Parameters<F>>) => ReturnType<F>`): 返回新的反转函数。
+
+## 示例
+
+```typescript
+import { flip } from 'es-toolkit/compat';
+
+function fn(a: any, b: any, c: any, d: any) {
+  return [a, b, c, d];
+}
+
+const flipped = flip(fn);
+flipped(1, 2, 3, 4); // => [4, 3, 2, 1]
+```

src/compat/function/flip.spec.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { flip } from './flip';
+
+describe('flip', () => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  function fn(a: any, b: any, c: any, d: any) {
+    // eslint-disable-next-line prefer-rest-params
+    return Array.from(arguments);
+  }
+
+  it('should flip arguments provided to `func`', () => {
+    const flipped = flip(fn);
+    expect(flipped('a', 'b', 'c', 'd')).toEqual(['d', 'c', 'b', 'a']);
+  });
+});

src/compat/function/flip.ts

@@ -0,0 +1,25 @@
+/**
+ * Creates a function that invokes `func` with arguments reversed.
+ *
+ * @param {F} func The function to flip arguments for.
+ * @returns {(...args: ReverseParameters<Parameters<F>>) => ReturnType<F>} Returns the new flipped function.
+ *
+ * @example
+ * function fn(a: any, b: any, c: any, d: any) {
+ *   return [a, b, c, d];
+ * }
+ *
+ * const flipped = flip(fn);
+ * flipped('a', 'b', 'c', 'd'); // => ['d', 'c', 'b', 'a']
+ */
+export function flip<F extends (...args: any[]) => any>(
+  func: F
+): (...args: ReverseParameters<Parameters<F>>) => ReturnType<F> {
+  return function (this: any, ...args: ReverseParameters<Parameters<F>>) {
+    return func.apply(this, args.reverse());
+  };
+}
+
+type ReverseParameters<T extends any[]> = T extends [infer First, ...infer Rest]
+  ? [...ReverseParameters<Rest>, First]
+  : [];

src/compat/index.ts

@@ -56,6 +56,7 @@ export { rearg } from './function/rearg.ts';
 export { curry } from './function/curry.ts';
 export { debounce } from './function/debounce.ts';
 export { throttle } from './function/throttle.ts';
+export { flip } from './function/flip.ts';
 
 export { get } from './object/get.ts';
 export { set } from './object/set.ts';