@bemoje/fn 0.0.1

package/index.d.ts

@@ -0,0 +1,247 @@
+import { ArraySlice } from 'type-fest';
+import { ArraySplice } from 'type-fest';
+import { Constructor } from 'type-fest';
+import { Subtract } from 'type-fest';
+import { TupleToObject } from 'type-fest';
+import { UnionToTuple } from 'type-fest';
+
+type Any = any;
+
+type TFunction<R = Any, A extends Any[] = Any[]> = (...args: A) => R;
+
+type AnyFunction<Ret = Any, Args extends Any[] = Any[]> = Constructor<Ret, Args> | TFunction<Ret, Args>;
+
+type AnyGetter = () => Any;
+
+type AnySetter = (value: Any) => Any;
+
+type Increment<T extends number> = Subtract<T, -1>;
+
+type RemoveArrayElement<T extends any[], Index extends number> = ArraySplice<T, Index, 1, []>;
+
+type ParametersWithout<T extends (...args: any[]) => any, Index extends number> = RemoveArrayElement<
+  Parameters<T>,
+  Index
+>;
+
+/**
+ * Removes elements from an array at specified indices.
+ */
+type RemoveArrayElements<T extends any[], Indices extends number[], Offset extends number = 0> = Indices extends [
+  infer First extends number,
+  ...infer Rest extends number[],
+]
+  ? RemoveArrayElements<
+      RemoveArrayElement<T, Subtract<First, Offset>>,
+      Rest,
+      Offset extends number ? Increment<Offset> : never
+    >
+  : T;
+
+/**
+ * Binds a specified argument to the provided function, returning a new function that requires
+ * only the remaining arguments at call time.
+ */
+declare function bindArg<
+  Ret extends (...args: ParametersWithout<T, Index>) => ReturnType<T>,
+  Index extends number = number,
+  Value = unknown,
+  T extends (...args: any[]) => any = (...args: any[]) => any,
+>(fn: T, boundArgIndex: Index, boundArgValue: Value): Ret;
+
+/**
+ * Binds specified arguments to the provided function, returning a new function that requires
+ * only the remaining arguments at call time.
+ *
+ * @typeParam T - The type of the function to be invoked with bound and unbound arguments.
+ * @typeParam BoundArgs - A partial mapping of indices in `Parameters<T>` to their bound values.
+ *
+ * @param fn - The original function whose arguments need to be partially applied.
+ * @param boundArgs - An object mapping argument indices to their respective bound values.
+ *
+ * @returns A function that, when invoked, applies both bound and unbound arguments in the correct order.
+ */
+declare function bindArgs<
+  T extends (...args: Any[]) => Any,
+  BoundArgs extends Partial<TupleToObject<Parameters<T>>>,
+>(
+  fn: T,
+  boundArgs: BoundArgs,
+): (...args: RemoveArrayElements<Parameters<T>, UnionToTuple<Extract<keyof BoundArgs, number>>>) => ReturnType<T>;
+
+/**
+ * Converts a function from a class method by by making the first argument take the place of the 'this' context.
+ * The reverse of @see thisify.
+ */
+declare function dethisify<T extends object, Args extends Any[], Ret>(
+  fn: (this: T, ...args: Args) => Ret,
+): (target: T, ...args: Args) => Ret;
+
+/**
+ * Wraps a function so that the given @see IFunctionSpyStrategy will be applied.
+ * @param func The function to wrap.
+ * @param spy The strategy to apply.
+ * @param options Options.
+ */
+declare function functionSpy<T, Data>(
+  func: TFunction,
+  spy: IFunctionSpyStrategy<T, Data>,
+  options?: FunctionSpyOptions<T, Data>,
+): TFunction;
+interface FunctionSpyOptions<T, Data> {
+  /**
+   * Whether the function is async.
+   * If provided, execution is a bit faster.
+   */
+  async?: boolean;
+  /**
+   * Predicate function that determines whether to skip the spy's actions for a given function call.
+   */
+  ignore?: IgnorePredicate<T, Data>;
+}
+/**
+ * @see functionSpy
+ */
+interface IFunctionSpyStrategy<T, Data> {
+  /**
+   * Action to perform before the function is invoked.
+   * @param thisContext The context in which the function is invoked.
+   * @param args The arguments passed to the function. Modify this array to change the arguments passed to the function.
+   * @returns Data to be passed to @see onReturn.
+   */
+  onInvoke<Args extends Any[]>(thisContext: T, args: Args): Data;
+  /**
+   * Action to perform before the function returns.
+   * @param data The data returned by @see onInvoke.
+   * @param retval The return value of the function.
+   * @returns The value to be returned by the wrapped function.
+   */
+  onReturn<Ret>(data: Data, retval: Ret): Ret;
+}
+type IgnorePredicate<T, Data> = (func: TFunction, spy: IFunctionSpyStrategy<T, Data>, thisContext?: T) => boolean;
+
+/**
+ * Preserves the name and length of a function or class constructor
+ */
+declare function preserveNameAndLength<
+  S extends ((...args: Any[]) => Any) | (new (...args: Any[]) => Any),
+  F extends ((...args: Any[]) => Any) | (new (...args: Any[]) => Any),
+>(source: S, target: F, adjustLengthBy?: number): F;
+
+/**
+ * Set the length of a function.
+ */
+declare function setLength<T extends object>(
+  length:
+    | number
+    | {
+        length: number;
+      },
+  target: T,
+): T;
+
+/**
+ * Set the name of a function.
+ */
+declare function setName<T extends object>(
+  name:
+    | string
+    | {
+        name: string;
+      },
+  target: T,
+): T;
+
+/**
+ * Returns a function that redirects or 'proxies' the 'this' context of the input function
+ * to a property of a given key.
+ */
+declare function thisProxy<ThisTarget extends This, This extends object, Args extends AnyArgs, Ret>(
+  fn: (this: This, ...args: Args) => Ret,
+  proxy: PropertyKey,
+): (this: ThisTarget, ...args: Args) => Ret;
+/**
+ * Returns a function that redirects or 'proxies' the 'this' context of the input function
+ * to a callback that returns the target object.
+ */
+declare function thisProxy<ThisTarget extends This, This extends object, Args extends AnyArgs, Ret>(
+  fn: (this: This, ...args: Args) => Ret,
+  proxy: (object: ThisTarget) => This,
+): (this: ThisTarget, ...args: Args) => Ret;
+type AnyArgs = any[];
+
+/**
+ * Converts a function to a class method by making the 'this' context the first argument.
+ */
+declare function thisify<T, Args extends Any[], Ret>(
+  fn: (target: T, ...args: Args) => Ret,
+): (this: T, ...args: Args) => Ret;
+type Thisify<T extends object, F extends (target: T, ...args: any[]) => Any> = (
+  this: T,
+  ...args: ArraySlice<Parameters<F>, 1>
+) => ReturnType<F>;
+
+/**
+ * Wraps a function to transform its return value using a transform function.
+ */
+declare function transformReturnValue<T, Args extends any[], Ret, NewRet>(
+  fn: (this: T, ...args: Args) => Ret,
+  transform: (value: Ret) => NewRet,
+): (this: T, ...args: Args) => NewRet;
+
+/**
+ * Wrap methods, getters and setters of an object with custom logic.
+ */
+declare function wrapMethods<T extends object>(target: T, strat: WrapMethodsStrategy<T>): T;
+type DescriptorMethodType = 'get' | 'set' | 'method';
+type MethodFilter<T extends object = object> = (
+  target: T,
+  key: string | symbol,
+  type: DescriptorMethodType,
+  descriptor: PropertyDescriptor,
+) => boolean;
+type MethodWrapper<T extends object = object> = (
+  target: T,
+  key: string | symbol,
+  method: AnyFunction,
+) => AnyFunction | undefined;
+type GetterWrapper<T extends object = object> = (
+  target: T,
+  key: string | symbol,
+  getter: AnyGetter,
+) => AnyGetter | undefined;
+type SetterWrapper<T extends object = object> = (
+  target: T,
+  key: string | symbol,
+  setter: AnySetter,
+) => AnySetter | undefined;
+interface WrapMethodsStrategy<T extends object = object> {
+  filter?: MethodFilter<T>;
+  onGetter?: GetterWrapper<T>;
+  onSetter?: SetterWrapper<T>;
+  onMethod?: MethodWrapper<T>;
+}
+
+export {
+  type DescriptorMethodType,
+  type FunctionSpyOptions,
+  type GetterWrapper,
+  type IFunctionSpyStrategy,
+  type IgnorePredicate,
+  type MethodFilter,
+  type MethodWrapper,
+  type SetterWrapper,
+  type Thisify,
+  type WrapMethodsStrategy,
+  bindArg,
+  bindArgs,
+  dethisify,
+  functionSpy,
+  preserveNameAndLength,
+  setLength,
+  setName,
+  thisProxy,
+  thisify,
+  transformReturnValue,
+  wrapMethods,
+};

package/index.mjs

@@ -0,0 +1,282 @@
+import { isAsyncFunction } from 'util/types';
+import { isFunction } from 'es-toolkit/predicate';
+import { range } from 'es-toolkit/math';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => {
+  return __defProp(target, 'name', { value, configurable: true });
+};
+
+// src/preserveNameAndLength.ts
+function preserveNameAndLength(source, target, adjustLengthBy = 0) {
+  return Object.defineProperties(target, {
+    name: {
+      configurable: true,
+      value: source.name,
+    },
+    length: {
+      configurable: true,
+      value: source.length + adjustLengthBy,
+    },
+  });
+}
+__name(preserveNameAndLength, 'preserveNameAndLength');
+
+// src/bindArg.ts
+function bindArg(fn, boundArgIndex, boundArgValue) {
+  return preserveNameAndLength(
+    fn,
+    (...args) => {
+      return fn(...args.slice(0, boundArgIndex), boundArgValue, ...args.slice(boundArgIndex));
+    },
+    -1,
+  );
+}
+__name(bindArg, 'bindArg');
+function bindArgs(fn, boundArgs) {
+  const boundIndices = Object.keys(boundArgs).map(Number);
+  const lastIndex = Math.max(fn.length - 1, ...boundIndices);
+  const indices = range(0, lastIndex + 1);
+  let offset = 0;
+  const argGetters = indices.map((index) => {
+    const isBound = Object.hasOwn(boundArgs, index);
+    const boundIndex = index;
+    const unboundIndex = index - (isBound ? offset++ : offset);
+    return isBound
+      ? () => {
+          return boundArgs[boundIndex];
+        }
+      : (args) => {
+          return args[unboundIndex];
+        };
+  });
+  return preserveNameAndLength(
+    fn,
+    (...args) => {
+      return fn(
+        ...argGetters.map((get) => {
+          return get(args);
+        }),
+      );
+    },
+    boundIndices.length * -1,
+  );
+}
+__name(bindArgs, 'bindArgs');
+
+// src/dethisify.ts
+function dethisify(fn) {
+  return preserveNameAndLength(
+    fn,
+    function (target, ...args) {
+      return fn.apply(target, args);
+    },
+    1,
+  );
+}
+__name(dethisify, 'dethisify');
+function functionSpy(func, spy, options = {}) {
+  if (options.async === false) {
+    return wrapSync(func, spy, options);
+  } else if (options.async || isAsyncFunction(func)) {
+    return wrapAsync(func, spy, options);
+  } else {
+    return wrapMaybeAsync(func, spy, options);
+  }
+}
+__name(functionSpy, 'functionSpy');
+function wrapMaybeAsync(func, spy, options = {}) {
+  const ignore = options.ignore;
+  if (ignore && ignore(func, spy)) {
+    return func;
+  }
+  return preserveNameAndLength(func, function (...args) {
+    if (ignore && ignore(func, spy, this)) {
+      return func.apply(this, args);
+    }
+    const data = spy.onInvoke(this, args);
+    const retval = func.apply(this, args);
+    if (retval instanceof Promise) {
+      return retval.then((retval2) => {
+        return spy.onReturn(data, retval2);
+      });
+    } else {
+      return spy.onReturn(data, retval);
+    }
+  });
+}
+__name(wrapMaybeAsync, 'wrapMaybeAsync');
+function wrapSync(func, spy, options = {}) {
+  const ignore = options.ignore;
+  if (ignore && ignore(func, spy)) {
+    return func;
+  }
+  return preserveNameAndLength(func, function (...args) {
+    if (ignore && ignore(func, spy, this)) {
+      return func.apply(this, args);
+    }
+    const data = spy.onInvoke(this, args);
+    const retval = func.apply(this, args);
+    return spy.onReturn(data, retval);
+  });
+}
+__name(wrapSync, 'wrapSync');
+function wrapAsync(func, spy, options = {}) {
+  const ignore = options.ignore;
+  if (ignore && ignore(func, spy)) {
+    return func;
+  }
+  return preserveNameAndLength(func, async function (...args) {
+    if (ignore && ignore(func, spy, this)) {
+      return await func.apply(this, args);
+    }
+    const data = spy.onInvoke(this, args);
+    const retval = await func.apply(this, args);
+    return spy.onReturn(data, retval);
+  });
+}
+__name(wrapAsync, 'wrapAsync');
+
+// src/setLength.ts
+function setLength(length, target) {
+  return Object.defineProperty(target, 'length', {
+    value: typeof length === 'number' ? length : length.length,
+    enumerable: false,
+    configurable: true,
+  });
+}
+__name(setLength, 'setLength');
+
+// src/setName.ts
+function setName(name, target) {
+  return Object.defineProperty(target, 'name', {
+    value: typeof name === 'string' ? name : name.name,
+    configurable: true,
+    enumerable: false,
+  });
+}
+__name(setName, 'setName');
+function thisProxy(fn, proxy) {
+  return isFunction(proxy) ? thisProxyCallback(fn, proxy) : thisProxyKey(fn, proxy);
+}
+__name(thisProxy, 'thisProxy');
+function thisProxyKey(fn, proxy) {
+  return preserveNameAndLength(fn, function (...args) {
+    const thisArg = this[proxy];
+    return fn.apply(thisArg, args);
+  });
+}
+__name(thisProxyKey, 'thisProxyKey');
+function thisProxyCallback(fn, proxy) {
+  return preserveNameAndLength(fn, function (...args) {
+    const thisArg = proxy(this);
+    return fn.apply(thisArg, args);
+  });
+}
+__name(thisProxyCallback, 'thisProxyCallback');
+
+// src/thisify.ts
+function thisify(fn) {
+  return preserveNameAndLength(
+    fn,
+    /* @__PURE__ */ __name(function f(...args) {
+      return fn(this, ...args);
+    }, 'f'),
+    -1,
+  );
+}
+__name(thisify, 'thisify');
+
+// src/transformReturnValue.ts
+function transformReturnValue(fn, transform) {
+  return preserveNameAndLength(fn, function (...args) {
+    const result = fn.apply(this, args);
+    return transform(result);
+  });
+}
+__name(transformReturnValue, 'transformReturnValue');
+function wrapMethods(target, strat) {
+  for (const [key, type, des] of iterateMethods(target)) {
+    if (strat.filter && !strat.filter(target, key, type, des)) {
+      continue;
+    }
+    if (type === 'method') {
+      if (!strat.onMethod) {
+        continue;
+      }
+      const orig = des.value;
+      const wrapped = strat.onMethod(target, key, orig);
+      if (!wrapped) {
+        continue;
+      }
+      Object.defineProperty(target, key, {
+        value: preserveNameAndLength(orig, wrapped),
+        configurable: des.configurable,
+        enumerable: des.enumerable,
+      });
+    } else if (type === 'get') {
+      if (!strat.onGetter) {
+        continue;
+      }
+      const orig = des.get;
+      const wrapped = strat.onGetter(target, key, orig);
+      if (!wrapped) {
+        continue;
+      }
+      Object.defineProperty(target, key, {
+        get: preserveNameAndLength(orig, wrapped),
+        configurable: des.configurable,
+        enumerable: des.enumerable,
+      });
+    } else if (type === 'set') {
+      if (!strat.onSetter) {
+        continue;
+      }
+      const orig = des.set;
+      const wrapped = strat.onSetter(target, key, orig);
+      if (!wrapped) {
+        continue;
+      }
+      Object.defineProperty(target, key, {
+        set: preserveNameAndLength(orig, wrapped),
+        configurable: des.configurable,
+        enumerable: des.enumerable,
+      });
+    }
+  }
+  return target;
+}
+__name(wrapMethods, 'wrapMethods');
+function* iterateMethods(target) {
+  for (const key of Reflect.ownKeys(target)) {
+    const des = Object.getOwnPropertyDescriptor(target, key);
+    if (!des || des.configurable === false) {
+      continue;
+    }
+    if (isFunction(des.value)) {
+      yield [key, 'method', des];
+    } else {
+      if (isFunction(des.get)) {
+        yield [key, 'get', des];
+      }
+      if (isFunction(des.set)) {
+        yield [key, 'set', des];
+      }
+    }
+  }
+}
+__name(iterateMethods, 'iterateMethods');
+
+export {
+  bindArg,
+  bindArgs,
+  dethisify,
+  functionSpy,
+  preserveNameAndLength,
+  setLength,
+  setName,
+  thisProxy,
+  thisify,
+  transformReturnValue,
+  wrapMethods,
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@bemoje/fn",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "function"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "default": "./index.mjs"
+    }
+  },
+  "dependencies": {
+    "es-toolkit": "^1.44.0",
+    "type-fest": "^5.4.4",
+    "@types/node": "^24.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Benjamin Møller Jensen",
+    "email": "bemoje@bemoje.net",
+    "url": "https://github.com/bemoje/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bemoje/mono.git",
+    "directory": "libs/fn"
+  }
+}