@ptolemy2002/react-proxy-context 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# React Proxy Context
+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.
+
+The functions are not exported as default, so you can import them in one of the following ways:
+```
+// ES6
+import { functionName } from '@ptolemy2002/react-utils';
+// CommonJS
+const { functionName } = require('@ptolemy2002/react-utils');
+```
+
+## Functions
+The following functions are available in the library:
+
+### createProxyContext
+#### 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.
+
+#### 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.
+
+## Components
+The following components are available in the library:
+
+### ProxyContextProvider
+#### 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.
+
+#### 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 context, and the third parameter is the previous value of the context. 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.
+
+## 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.
+
+#### 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).
+- `listenReinit` (Boolean): Whether to listen to full reassignments of the context and re-render when they occur. Default 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.
+
+## 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
+- @types/is-callable: ^1.1.2
+- is-callable: ^1.2.7
+- nanoid: ^5.0.7
+- @ptolemy2002/react-mount-effects: ^1.1.4
+- @ptolemy2002/react-force-rerender: ^1.0.4
+- @ptolemy2002/js-utils: ^1.0.3
+
+## Commands
+The following commands exist in the project:
+
+- `npm run uninstall` - Uninstalls all dependencies for the library
+- `npm run reinstall` - Uninstalls and then Reinstalls all dependencies for the library
+- `npm run example-uninstall` - Uninstalls all dependencies for the example app
+- `npm run example-install` - Installs all dependencies for the example app
+- `npm run example-reinstall` - Uninstalls and then Reinstalls all dependencies for the example app
+- `npm run example-start` - Starts the example app after building the library
+- `npm run build` - Builds the library
+- `npm run release` - Publishes the library to npm without changing the version
+- `npm run release-patch` - Publishes the library to npm with a patch version bump
+- `npm run release-minor` - Publishes the library to npm with a minor version bump
+- `npm run release-major` - Publishes the library to npm with a major version bump

package/index.js

@@ -0,0 +1,124 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var src_exports = {};
+__export(src_exports, {
+  ProxyContextProvider: () => ProxyContextProvider,
+  createProxyContext: () => createProxyContext,
+  useProxyContext: () => useProxyContext
+});
+module.exports = __toCommonJS(src_exports);
+var import_react = __toESM(require("react"));
+var import_nanoid = require("nanoid");
+var import_is_callable = __toESM(require("is-callable"));
+var import_react_force_rerender = __toESM(require("@ptolemy2002/react-force-rerender"));
+var import_react_mount_effects = require("@ptolemy2002/react-mount-effects");
+var import_js_utils = require("@ptolemy2002/js-utils");
+function createProxyContext(defaultValue, name) {
+  if (typeof Proxy == "undefined") throw new Error("Proxy is not supported in this environment.");
+  const context = (0, import_react.createContext)(defaultValue);
+  context.name = name;
+  return context;
+}
+function ProxyContextProvider({ contextClass, children, value, onChange, proxyRef }) {
+  const changeSubscribers = (0, import_react.useRef)({});
+  const objRef = (0, import_react.useRef)();
+  const contextRef = (0, import_react.useRef)({});
+  const subscribe = (0, import_react.useCallback)((callback, deps, listenReinit = true) => {
+    const id = (0, import_nanoid.nanoid)();
+    changeSubscribers.current[id] = {
+      deps,
+      callback,
+      listenReinit
+    };
+    return id;
+  }, []);
+  const unsubscribe = (0, import_react.useCallback)((id) => {
+    delete changeSubscribers.current[id];
+  }, []);
+  const set = (0, import_react.useCallback)((newObj) => {
+    if (newObj !== objRef.current) {
+      const prevObj = objRef.current;
+      if (!(0, import_js_utils.isNullOrUndefined)(newObj)) {
+        objRef.current = new Proxy(newObj, {
+          get: function(target, prop) {
+            const result = Reflect.get(target, prop, objRef.current);
+            if ((0, import_is_callable.default)(result)) {
+              return result.bind(objRef.current);
+            } else {
+              return result;
+            }
+          },
+          set: function(target, prop, value2) {
+            const prevValue = target[prop];
+            Reflect.set(target, prop, value2, objRef.current);
+            value2 = target[prop];
+            Object.values(changeSubscribers.current).forEach((subscriber) => {
+              if (!subscriber.deps || subscriber.deps.includes(prop) && prevValue !== value2 || subscriber.deps.some((subProp) => (0, import_is_callable.default)(subProp) && subProp(prop, value2, prevValue, objRef.current))) {
+                subscriber.callback(prop, value2, prevValue);
+              }
+            });
+            if ((0, import_is_callable.default)(onChange)) onChange(prop, value2, prevValue);
+            return true;
+          }
+        });
+      }
+      Object.values(changeSubscribers.current).forEach((subscriber) => {
+        if (subscriber.listenReinit) subscriber.callback(null, objRef.current, prevObj);
+      });
+      proxyRef && (proxyRef.current = objRef.current);
+      if ((0, import_is_callable.default)(onChange)) onChange(null, objRef.current, prevObj);
+    }
+    return objRef.current;
+  }, [onChange, proxyRef]);
+  if (objRef.current === void 0) objRef.current = set(value);
+  contextRef.current.obj = objRef.current;
+  contextRef.current.set = set;
+  contextRef.current.subscribe = subscribe;
+  contextRef.current.unsubscribe = unsubscribe;
+  return /* @__PURE__ */ import_react.default.createElement(contextClass.Provider, { value: contextRef.current }, children);
+}
+function useProxyContext(contextClass, deps, onChange, listenReinit = true) {
+  const context = (0, import_react.useContext)(contextClass);
+  const forceRerender = (0, import_react_force_rerender.default)();
+  const id = (0, import_react.useRef)(null);
+  if (context === void 0) {
+    throw new Error(`No ${contextClass.name} provider found.`);
+  }
+  (0, import_react_mount_effects.useMountEffect)(() => {
+    id.current = context?.subscribe((prop, current, prev) => {
+      forceRerender();
+      if ((0, import_is_callable.default)(onChange)) onChange(prop, current, prev);
+    }, deps, listenReinit);
+  });
+  (0, import_react_mount_effects.useUnmountEffect)(() => {
+    context?.unsubscribe(id.current);
+  });
+  return [context?.obj, context?.set];
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@ptolemy2002/react-proxy-context",
+    "version": "1.0.0",
+    "main": "index.js",
+    "files": [
+        "index.js"
+    ],
+    "scripts": {
+        "build": "esbuild src/index.js --bundle --format=cjs --outfile=index.js --loader:.js=jsx --external:react --external:react-dom --external:@types/react --external:@types/react-dom --external:is-callable --external:nanoid --external:@ptolemy2002/react-mount-effects --external:@ptolemy2002/react-force-rerender --external:@ptolemy2002/js-utils",
+        "postinstall": "npx typesync",
+        "uninstall": "bash ./scripts/uninstall.sh",
+        "reinstall": "bash ./scripts/reinstall.sh",
+        "example-uninstall": "bash ./scripts/example-uninstall.sh",
+        "example-install": "bash ./scripts/example-install.sh",
+        "example-reinstall": "bash ./scripts/example-reinstall.sh",
+        "example-start": "bash ./scripts/example-start.sh",
+        "release": "bash ./scripts/release.sh",
+        "release-patch": "bash ./scripts/release.sh patch",
+        "release-minor": "bash ./scripts/release.sh minor",
+        "release-major": "bash ./scripts/release.sh major"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Ptolemy2002/react-proxy-context",
+        "directory": "lib"
+    },
+    "description": "React Context with Support for Mutation with Proxies",
+    "license": "ISC",
+    "peerDependencies": {
+        "@types/react": "^18.3.3",
+        "@types/react-dom": "^18.3.0",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
+        "@types/is-callable": "^1.1.2",
+        "is-callable": "^1.2.7",
+        "nanoid": "^5.0.7",
+        "@ptolemy2002/react-mount-effects": "^1.1.4",
+        "@ptolemy2002/react-force-rerender": "^1.0.4",
+        "@ptolemy2002/js-utils": "^1.0.3"
+    },
+    "devDependencies": {
+        "esbuild": "^0.23.0"
+    }
+}