@ptolemy2002/react-proxy-context 1.2.1 → 2.0.1

package/README.md

@@ -2,65 +2,107 @@
 This library is a solution for React that uses Javascript Proxies to allow React context consumers to listen to mutations as well as reassignments. Another benefit is that you can listen to the mutation of only specific properties. I find that many consider this style more intuitive to work with, though it is considered bad practice by others. A limitation is that it is only able to track direct mutations, not mutations that occur in nested arrays or objects, so those will still require recreation and reassignment.
 
 The functions are not exported as default, so you can import them in one of the following ways:
-```
+```javascript
 // ES6
 import { functionName } from '@ptolemy2002/react-proxy-context';
 // CommonJS
 const { functionName } = require('@ptolemy2002/react-proxy-context');
 ```
 
+## Type Reference
+```typescript
+type ContextWithName<T> = React.Context<T> & { name: string };
+
+type OnChangePropCallback<T> =
+    <K extends keyof T>(prop: K, current: T[K], prev?: T[K]) => void
+;
+type OnChangeReinitCallback<T> =
+    (current: T, prev?: T) => void
+;
+
+type Dependency<T> = keyof T | (
+    <K extends keyof T>(prop: K, current: T[K], prev: T[K], obj: T) => boolean
+) | null | undefined | false;
+
+type ProxyContextValue<T> = {
+    obj: T;
+    set: (newObj: T) => T;
+    subscribe: (
+        propCallback: OnChangePropCallback<T>,
+        reinitCallback: OnChangeReinitCallback<T>,
+        deps: Dependency<T>[]
+    ) => string;
+    unsubscribe: (id: string) => void;
+};
+
+type ProxyContextProviderProps<T> = {
+    children: ReactNode;
+    value: T;
+    onChangeProp?: OnChangePropCallback<T>;
+    onChangeReinit?: OnChangeReinitCallback<T>;
+    proxyRef?: React.MutableRefObject<T>;
+};
+
+type UseProxyContextResult<T> = HookResultData<{
+    value: T;
+    set: (newObj: T) => T;
+}, readonly [T, (newObj: T) => T]>;
+```
+
 ## Functions
 The following functions are available in the library:
 
-### createProxyContext
+### createProxyContext<T>
 #### Description
-Creates a new instance of the ProxyContext, essentially to be used as the context type, with the specified default value and name. This is effectively just the normal React createContext function, but with a check to ensure that the browser supports Proxies.
+Creates a new instance of the ProxyContext, essentially to be used as the context type, with the specified name. This is effectively just the normal React createContext function, but with a check to ensure that the browser supports Proxies. `T` represents the type of the object that will be stored in the context.
 
 #### Parameters
-- `defaultValue` (Object): The default value of the context. This is what is reported when the context is not provided.
 - `name` (String): The name of the context. This is used for debugging purposes.
 
 #### Returns
-Object - The ProxyContext object, which is a React context object.
+`ContextWithName<ProxyContextValue<T> | undefined>` - The context object that can be used in a provider.
 
-## Components
-The following components are available in the library:
-
-### ProxyContextProvider
+### createProxyContextProvider<T extends object>
 #### Description
-A component that provides context of the specified class to its children using proxies. `useProxyContext` can only be used to access the context provided by this component.
+Creates a new proxy context provider component with the specified type. `ProxyContextProvider` is no longer used due to a TypeScript limitation that prevents the context type from being inferred.
 
-#### Props
-- `contextClass` (Object): The class of the context to provide. This is the class that was created using `createProxyContext`.
-- `value` (Object): The value of the context. This is what is reported when the context is not provided.
-- `onChange` (Function): A function that is called whenever the context is changed. The first parameter is the property that was changed (null if it was reassignment), the second parameter is the current value of the property, and the third parameter is the previous value of the property. This is useful for listening to changes in the provider's parent component.
-- `proxyRef` (Object): A ref object that is assigned the proxy object of the context. This is useful for accessing the proxy object directly by the provider's parent component.
+#### Parameters
+- `contextClass` (`ContextWithName<ProxyContextValue<T> | undefined>`): The context class that was created using `createProxyContext`.
+
+#### Returns
+`React.MemoExoticComponent<FunctionComponent<ProxyContextProviderProps<T> & { renderDeps?: any[] }>>` - The provider component that can be used in the React tree. The resulting component is memoized to prevent unnecessary re-renders, but the `renderDeps` prop can be used to force a re-render when the specified dependencies change (necessary when working with the children prop).
+
+The component has the following other props:
+- `value` (T): The value of the context. This is what is reported when the context is not provided.
+- `onChangeProp` (`OnChangePropCallback<T>`): A function that is called whenever a property of the context is changed. The first parameter is the property that was changed, the second parameter is the current value of the property, and the third parameter is the previous value of the property. This is useful for listening to changes in the provider's parent component.
+- `onChangeReinit` (`OnChangeReinitCallback<T>`): A function that is called whenever the context is reinitialized. The first parameter is the current value of the context, and the second parameter is the previous value of the context. This is useful for listening to changes in the provider's parent component.
+- `proxyRef` (`React.MutableRefObject<T>`): A ref object that is assigned the proxy object of the context. This is useful for accessing the proxy object directly by the provider's parent component.
 
 ## Hooks
 The following hooks are available in the library:
 
-### useProxyContext
-A hook that uses the context provided by the `ProxyContextProvider` component. This hook also provides options to choose which properties to listen to and whether to listen to full reassignments.
+### useProxyContext<T>
+A hook that uses the context provided by the `ProxyContextProvider` component. This hook also provides options to choose which properties to listen to and whether to listen to full reassignments. `T` represents the type of the object that is stored in the context.
 
 #### Parameters
-- `contextClass` (Object): The class of the context to use. This is the class that was created using `createProxyContext`.
-- `deps` (Array): An array of dependencies to listen to. If any of these properties on the context change, the hook will re-render. If this is falsy, any mutation will trigger a re-render. You can also specify a function that returns a boolean to determine whether to re-render (provided with the same arguments as `onChange` would be and a 4th argument that is the current value of the context).
-- `onChange` (Function): A function that is called whenever the context is changed. The first parameter is the property that was changed (null if it was reassignment), the second parameter is the current value of the property, and the third parameter is the previous value of the property. This is useful for listening to changes in the provider's parent component.
-- `listenReinit` (Boolean): Whether to listen to full reassignments of the context and re-render when they occur. Default is `true`.
+- `contextClass` (`ContextWithName<ProxyContextValue<T> | undefined>`): The context class that was created using `createProxyContext`.
+- `deps` (`Dependency<T>[] | null`): An array of dependencies to listen to. If any of these properties on the context change, the hook will re-render. If this is falsy, any mutation will trigger a re-render. You can also specify a function that returns a boolean to determine whether to re-render. If this is null, the hook will re-render on any mutation. By default, this is an empty array.
+- `onChangeProp` (`OnChangePropCallback<T> | undefined`): A function that is called whenever a property of the context is changed. The first parameter is the property that was changed, the second parameter is the current value of the property, and the third parameter is the previous value of the property. This is useful for listening to changes in the provider's parent component.
+- `onChangeReinit` (`OnChangeReinitCallback<T> | undefined`): A function that is called whenever the context is reinitialized. The first parameter is the current value of the context, and the second parameter is the previous value of the context. This is useful for listening to changes in the provider's parent component.
+- `listenReinit` (`boolean`): Whether to listen to full reassignments of the context. If this is true, the hook will re-render whenever the context is reinitialized. By default, this is true.
 
 #### Returns
-Array - An array with the first element being the current value of the context and the second element being a setter function to reassign the context.
-
-## Meta
-This is a React Library Created by Ptolemy2002's [cra-template-react-library](https://www.npmjs.com/package/@ptolemy2002/cra-template-react-library) template in combination with [create-react-app](https://www.npmjs.com/package/create-react-app). It contains methods of building and publishing your library to npm.
-For now, the library makes use of React 18 and does not use TypeScript.
+`UseProxyContextResult<T>` - An object containing the current value of the context and a function to set the context. The function returns the new value of the context wrapped in a `Proxy`.
 
 ## Peer Dependencies
 These should be installed in order to use the library, as npm does not automatically add peer dependencies to your project.
-- @types/react: ^18.3.3
-- @types/react-dom: ^18.3.0
-- react: ^18.3.1
-- react-dom: ^18.3.1
+- `react^18.3.1`
+- `react-dom^18.3.1`
+- `@ptolemy2002/js-utils^3.0.2`
+- `@ptolemy2002/react-utils^3.0.0`
+- `@ptolemy2002/react-force-rerender^2.0.0`
+- `@ptolemy2002/react-hook-result^2.1.1`
+- `@ptolemy2002/react-mount-effects^2.0.0`
 
 ## Commands
 The following commands exist in the project:

package/dist/main.d.ts

@@ -0,0 +1,30 @@
+import { Context, ReactNode } from 'react';
+import { HookResultData } from '@ptolemy2002/react-hook-result';
+export type ContextWithName<T> = Context<T> & {
+    name: string;
+};
+export type OnChangePropCallback<T> = <K extends keyof T>(prop: K, current: T[K], prev?: T[K]) => void;
+export type OnChangeReinitCallback<T> = (current: T, prev?: T) => void;
+export type ProxyContextValue<T> = {
+    obj: T;
+    set: (newObj: T) => T;
+    subscribe: (propCallback: OnChangePropCallback<T>, reinitCallback: OnChangeReinitCallback<T>, deps: Dependency<T>[] | null) => string;
+    unsubscribe: (id: string) => void;
+};
+export declare function createProxyContext<T>(name: string): ContextWithName<ProxyContextValue<T> | undefined>;
+export type Dependency<T> = keyof T | (<K extends keyof T>(prop: K, current: T[K], prev: T[K], obj: T) => boolean) | null | undefined | false;
+export type ProxyContextProviderProps<T> = {
+    children: ReactNode;
+    value: T;
+    onChangeProp?: OnChangePropCallback<T>;
+    onChangeReinit?: OnChangeReinitCallback<T>;
+    proxyRef?: React.MutableRefObject<T>;
+};
+export declare function createProxyContextProvider<T extends object>(contextClass: ContextWithName<ProxyContextValue<T> | undefined>): import('react').MemoExoticComponent<import('react').FunctionComponent<ProxyContextProviderProps<T> & {
+    renderDeps?: any[];
+}>>;
+export type UseProxyContextResult<T> = HookResultData<{
+    value: T;
+    set: (newObj: T) => T;
+}, readonly [T, (newObj: T) => T]>;
+export declare function useProxyContext<T>(contextClass: ContextWithName<ProxyContextValue<T> | undefined>, deps?: Dependency<T>[] | null, onChangeProp?: OnChangePropCallback<T>, onChangeReinit?: OnChangeReinitCallback<T>, listenReinit?: boolean): UseProxyContextResult<T>;