useProxy

state

Installation

npx usehooks-cli@latest add use-proxy

Description

A React hook that creates and manages JavaScript Proxy objects, enabling you to intercept and customize operations performed on objects (such as property lookup, assignment, enumeration, function invocation, etc.). Perfect for creating reactive objects, validation, logging, or data transformation.

Parameters

Name	Type	Default	Description
initialTarget	T extends object	-	The initial target object to be proxied
handler	ProxyHandler<T>	-	An object that defines which operations will be intercepted and how to redefine intercepted operations

Return Type

UseProxyReturn<T>

Property	Type	Description
proxy	T	The proxy object that intercepts operations on the target
target	T	The original target object
updateTarget	(newTarget: T \| ((prevTarget: T) => T)) => void	Function to update the target object
revoke	() => void	Function to revoke the proxy, making it unusable
isRevoked	boolean	Whether the proxy has been revoked

Examples

Property Access Logging

Log all property access on an object

const { proxy } = useProxy(
  { name: 'John', age: 30 },
  {
    get(target, prop) {
      console.log(`Accessing property: ${String(prop)}`);
      return target[prop];
    }
  }
);

// Usage: proxy.name will log "Accessing property: name"

Property Validation

Validate property assignments

const { proxy } = useProxy(
  { age: 0 },
  {
    set(target, prop, value) {
      if (prop === 'age' && (typeof value !== 'number' || value < 0)) {
        throw new Error('Age must be a positive number');
      }
      target[prop] = value;
      return true;
    }
  }
);

// proxy.age = -5; // Throws error

Default Values

Provide default values for undefined properties

const { proxy } = useProxy(
  {},
  {
    get(target, prop) {
      return prop in target ? target[prop] : 'default';
    }
  }
);

// proxy.anyProperty returns 'default' if not set

Revocable Proxy

Create a proxy that can be revoked

const { proxy, revoke, isRevoked } = useProxy(
  { data: 'sensitive' },
  {
    get(target, prop) {
      console.log('Access granted');
      return target[prop];
    }
  }
);

// Later revoke access
revoke();
console.log(isRevoked); // true

Dependencies

react

Notes

•The proxy is recreated when the target or handler changes
•Once revoked, the proxy becomes unusable and operations will throw TypeError
•The hook uses Proxy.revocable() to allow controlled revocation
•All handler methods are optional - omitted traps forward to the target
•Perfect for implementing reactive objects, validation, or debugging

Implementation

"use client";

import { useState, useCallback, useMemo } from "react";

type ProxyHandler<T extends object> = {
  get?: (target: T, property: string | symbol, receiver: any) => any;
  set?: (
    target: T,
    property: string | symbol,
    value: any,
    receiver: any
  ) => boolean;
  has?: (target: T, property: string | symbol) => boolean;
  deleteProperty?: (target: T, property: string | symbol) => boolean;
  ownKeys?: (target: T) => ArrayLike<string | symbol>;
  getOwnPropertyDescriptor?: (
    target: T,
    property: string | symbol
  ) => PropertyDescriptor | undefined;
  defineProperty?: (
    target: T,
    property: string | symbol,
    attributes: PropertyDescriptor
  ) => boolean;
  preventExtensions?: (target: T) => boolean;
  getPrototypeOf?: (target: T) => object | null;
  isExtensible?: (target: T) => boolean;
  setPrototypeOf?: (target: T, prototype: object | null) => boolean;
  apply?: (target: T, thisArg: any, argArray: any[]) => any;
  construct?: (target: T, argArray: any[], newTarget: Function) => object;
};

interface UseProxyReturn<T extends object> {
  proxy: T;
  target: T;
  updateTarget: (newTarget: T | ((prevTarget: T) => T)) => void;
  revoke: () => void;
  isRevoked: boolean;
}

export function useProxy<T extends object>(
  initialTarget: T,
  handler: ProxyHandler<T>
): UseProxyReturn<T> {
  const [target, setTarget] = useState<T>(initialTarget);
  const [isRevoked, setIsRevoked] = useState(false);

  // Create a revocable proxy
  const { proxy, revoke: revokeProxy } = useMemo(() => {
    if (isRevoked) {
      return { proxy: target, revoke: () => {} };
    }
    return Proxy.revocable(target, handler);
  }, [target, handler, isRevoked]);

  const updateTarget = useCallback(
    (newTarget: T | ((prevTarget: T) => T)) => {
      if (isRevoked) {
        console.warn("Cannot update target of a revoked proxy");
        return;
      }
      setTarget((prevTarget) =>
        typeof newTarget === "function"
          ? (newTarget as (prevTarget: T) => T)(prevTarget)
          : newTarget
      );
    },
    [isRevoked]
  );

  const revoke = useCallback(() => {
    if (!isRevoked) {
      revokeProxy();
      setIsRevoked(true);
    }
  }, [revokeProxy, isRevoked]);

  return {
    proxy: isRevoked ? target : proxy,
    target,
    updateTarget,
    revoke,
    isRevoked,
  };
}

useLocalStorage

CLI Docs All Hooks

useSet