New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
react-aptor
Advanced tools
react-aptor - npm Package Compare versions
Comparing version 1.2.1 to 1.3.0
| { | ||
| "name": "react-aptor", | ||
| "version": "1.2.1", | ||
| "version": "1.3.0", | ||
| "private": false, | ||
@@ -5,0 +5,0 @@ "description": "React API connector", |
131
README.md
| <h1 align="center">React Aptor</h1> | ||
| <p align="center"><img src="./doc/assets/logo.svg" alt="react aptor logo" width="450"></p> | ||
| <p align="center">Minimal API Connector for react</p> | ||
| <p align="center"> | ||
| Minimal API Connector for react | ||
| <br> | ||
| <img src="https://img.shields.io/badge/Tree%20Shakeable-d4e157" alt="tree-shakeable" /> | ||
| <img src="https://img.shields.io/badge/Zero%20Dependencies-ffbfbf" alt="zero dependencies" /> | ||
| <img src="https://img.shields.io/badge/Side%20Effect%20Free-ffeb3b" alt="side-effect free" /> | ||
| </p> | ||
| <p align="center"> | ||
| <a href="https://github.com/amirHossein-Ebrahimi/react-aptor/blob/master/license"> | ||
@@ -21,6 +27,5 @@ <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="license" /> | ||
| <p align="right"> | ||
| <a href="./doc/localization/fa.md">آموزش فارسی</a> | ||
| </p> | ||
| English | <a href="./doc/localization/fa.md">Persian</a> | (<a href="https://github.com/amirHossein-Ebrahimi/react-aptor/issues/new">add your langauge</a>) | ||
| Don’t waste your time by finding react version of your favorite javascript package, keep control of your `API` now. | ||
@@ -35,4 +40,4 @@ | ||
| Connecting vanilla third parties to react is not a routine task especially those that need to change the DOM. | ||
| On the other hand, these packages might be developed by different teams, hence development progress can be one step behind of the original or even be terminated at any time. Also, wrong abstraction or bad design patterns may interrupt the progress of these react`-something` packages. | ||
| Connecting vanilla third parties to react is not a routine task especially for those that need to change the DOM. | ||
| On the other hand, these packages might be developed by different teams, hence development progress can be one step behind the original or even be terminated at any time. Also, wrong abstraction or bad design patterns may interrupt the progress of these `react-xyz` packages. | ||
@@ -45,5 +50,5 @@ If you are still not convinced you can read this [article](https://dev.to/amirhe/aptor-is-all-you-need-3din) | ||
| - Extensively usage of memorization to improve performance or prevent extra re-renders | ||
| - Other duplication layer for all API definition in react that increase the project size | ||
| - Another duplication layer for all API definitions in react that increase the project size | ||
| - Rely on a global scope (e.g. window) for internal settings (making it impossible to have more than one instance) | ||
| - backward compatible updates of the base package need another update for react-* package | ||
| - backward compatible updates of the base package need another update for the react-xyz package | ||
@@ -63,3 +68,3 @@ ## react-aptor | ||
| <summary>Manageable</summary> | ||
| Your used/defined APIs are entirely under your control. Make it possible to define a slice of APIs which you are surely going to use. | ||
| Your used/defined APIs are entirely under your control. Make it possible to define a slice of APIs that you are surely going to use. | ||
| </details> | ||
@@ -107,4 +112,4 @@ | ||
| > | ||
| > The `params` are optional parameters that are passed by react-aptor and define by you. see the third step. | ||
| > The params will be passed by you and will be more clear in third step. | ||
| > The `params` are optional parameters that are passed by react-aptor and defined by you. see the third step. | ||
| > The params will be passed by you and will be more clear in the third step. | ||
| > | ||
@@ -127,9 +132,9 @@ > name this file **construct.js** as convention ✨. | ||
| The react-aptor will pass the latest instance of your third-party which has been defined in the first step by **instantiate** function along with **params** to **getAPI** function. | ||
| The react-aptor will pass the latest instance of your third party which has been defined in the first step by the **instantiate** function along with **params** to **getAPI** function. | ||
| > The `instance` is returned instance of your third-party. | ||
| > The `instance` is returned instance of your third party. | ||
| > Technically it is exactly going to be **instantiate(node, params)** | ||
| > | ||
| > The `params` are optional parameters that are passed by react-aptor and define by you. see the third step. | ||
| > The params will be passed by you and will be more clear in third step. | ||
| > The `params` are optional parameters that are passed by react-aptor and defined by you. see the third step. | ||
| > The params will be passed by you and will be more clear in the third step. | ||
| > | ||
@@ -168,3 +173,3 @@ > name this file **api.js** as convention ✨. | ||
| **ref** | ||
| For the connection phase, you need to define a **forwardRef** component. The `useAptor` hook needs forwarded-ref as the first argument, this is necessary to bind all your defined api to this ref. | ||
| For the connection phase, you need to define a **forwardRef** component. The `useAptor` hook needs forwarded-ref as the first argument, this is necessary to bind all your defined API to this ref. | ||
@@ -174,7 +179,7 @@ **configuration** | ||
| > The `params` doesn't have any limitation, it can be any arbitrary type e.g. undefined, number, string or an object containing all of them. The params will be then passed to your instantiate and getAPI function, as you saw in the first and second steps. | ||
| > Params is the best place to connect props to your low-level api it means ”No Need” for extra function generation 🥳 | ||
| > The `params` doesn't have any limitation, it can be any arbitrary type e.g. undefined, number, string, or an object containing all of them. The params will be then passed to your instantiate and getAPI function, as you saw in the first and second steps. | ||
| > Params is the best place to connect props to your low-level API it means ”No Need” for extra function generation 🥳 | ||
| **deps** | ||
| Is the same as Dependencies array default value is `[]` but you can override it as the third and lat argument of useAptor. It maybe needed in situation which you want to force re-instantiate by some prop change. It will use shallow comparison (as react do) for deps array and will call your `instantiate` & `getApI` in a row. | ||
| Is the same as Dependencies array default value is `[]` but you can override it as the third and last argument of useAptor. It may be needed in a situation in which you want to force re-instantiate by some prop change. It will use shallow comparison (as react do) for dependency array and will call your `instantiate` & `getAPI` in a row. | ||
@@ -214,3 +219,3 @@ ### API usage | ||
| > In case you need `ref.current` more than one time, it is a good idea to rename it at the first place | ||
| > In case you need `ref.current` more than one time, it is a good idea to rename it in the first place | ||
@@ -226,8 +231,8 @@ ```jsx | ||
| ### 💡 Can I remove if check in handlers | ||
| ### 💡 Can I remove if check-in handlers | ||
| Cause the default value for ref can be undefined (in **createRef**) and null (in **useRef**) Typescript will complain about possibility for not-existence of apis. [see more](https://fettblog.eu/typescript-react/hooks/#useref). | ||
| In normal world react will bind your API to given ref after the Connector mount | ||
| In a normal world react will bind your API to the given ref after the Connector mount | ||
| If you're using ref in useEffect or somewhere which is guaranteed to have the ref bounded to values, you can return proxy object in your getAPI function to bind all api functions simultaneously. | ||
| If you're using ref in useEffect or somewhere which is guaranteed to have the ref bounded to values, you can return a proxy object in your `getAPI` function to bind all api functions simultaneously. | ||
@@ -257,5 +262,5 @@ ```js | ||
| ### 💡 Micro api instructions | ||
| ### 💡 Micro API instructions | ||
| > You can access all of you apis via `this` keyword | ||
| > You can access all of your APIs via `this` keyword | ||
@@ -276,9 +281,9 @@ ```js | ||
| > It's better to start name of this internal functions with `_` | ||
| > It's better to start the name of these internal functions with `_` | ||
| ### 💡 The `this` problem in API object | ||
| In a case you see this keyword usage in third-party API | ||
| you must specifying `this` something other than returned API object. | ||
| The following examples is for howler integration using react-aptor: | ||
| In a case, you see this keyword usage in third-party API | ||
| you must specify `this` something other than returned API object. | ||
| The following examples are for howler integration using react-aptor: | ||
@@ -308,11 +313,13 @@ ```js | ||
| ### 💡 How to make a custom react integeration packge using react-aptor | ||
| ### 💡 How to make a custom react integration package using react-aptor | ||
| 1. Name you packge **raptor-something** :) | ||
| 2. Use minimum possible configuration for your api | ||
| 1. Name your package **raptor-something** :) | ||
| 2. Use minimum possible configuration for your API | ||
| 3. Interact to props change in your component using `useEffect` and proper `deps` array | ||
| 4. Bind another ref to you Connector using fork-ref idea, for other possible usage | ||
| 4. Bind another ref to your Connector using the fork-ref idea | ||
| See all in action in **[raptor-howler-example](https://github.com/amirHossein-Ebrahimi/raptor-howler/tree/master/example)** | ||
| For another possible usage see our production ready examples: | ||
| - **[plyr-react](https://github.com/chintan9/plyr-react)** | ||
| - **[raptor-howler-example](https://github.com/amirHossein-Ebrahimi/raptor-howler/tree/master/example)** | ||
@@ -324,3 +331,3 @@ ## core | ||
| The react **useRef** or **createRef** ref instance which has been passed throw **react.forwardRef** method. | ||
| your api will be stored in this ref. | ||
| your API will be stored in this ref. | ||
@@ -333,3 +340,3 @@ ### **configuration** _`required`_ | ||
| A function that receives probable bounded-node and params. It then returns an instance of your third-party. | ||
| A function that receives probable bounded-node and params. It then returns an instance of your third party. | ||
@@ -340,3 +347,3 @@ - ### **destroy** | ||
| A function that receives previous created instance and params. It is useful when you want to perform the cleanup before new instance creation. e.g. **remove event listeners**, **free up allocated memories**, **destroy internally** & etc | ||
| A function that receives previously created instances and params. It is useful when you want to perform the cleanup before new instance creation. e.g. **remove event listeners**, **free up allocated memories**, **destroy internally** & etc | ||
@@ -347,3 +354,3 @@ - ### **getAPI** _`required`_ | ||
| A function which receives instance of you third-party and params. It then returns a key-value pair object for api handlers. | ||
| A function that receives instances of your third-party and params. It then returns a key-value pair object for API handlers. | ||
@@ -356,3 +363,3 @@ - ### **params** `any` | ||
| React dependencies array for re-instantiating your third-party-packages. It will call `instantiate` with latest node, params when ever shallow comparison for with the previous deps array finds inequality. | ||
| React dependencies array for re-instantiating your third-party packages. It will call `instantiate` with the latest node, params whenever shallow comparison for with the previous deps array finds inequality. | ||
@@ -363,35 +370,41 @@ --- | ||
| 🎨 Designer (**BTC**): | ||
| `bc1q9fahyct3lrdz47pjf4kfxvsyum2dm74v2hv9xl` | ||
| 💻 Developer/Maintainer (**BTC**): | ||
| `bc1qq8qq63ex7svkkjdjn5axu8angfxytvs83nlujk` | ||
| ## Samples | ||
| 🎨 Designer (**BTC**): | ||
| `bc1q9fahyct3lrdz47pjf4kfxvsyum2dm74v2hv9xl` | ||
| **NOTE**: Add your favourite packge do the following list by creating a [new issue](https://github.com/amirHossein-Ebrahimi/react-aptor/issues). | ||
| ## Color Palettes | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
| ### [Quill.js](https://github.com/quilljs/quill) + `typescript` | ||
| ## Samples | ||
| > Quill is a free, open source WYSIWYG editor built for the modern web. <img src="https://img.shields.io/github/stars/quilljs/quill?style=social" /> > <a href="https://codesandbox.io/s/react-aptor--quill-iqwcd"><img src="https://codesandbox.io/static/img/play-codesandbox.svg"></a> | ||
| **NOTE**: Add your favorite package to the following list by creating a [new issue](https://github.com/amirHossein-Ebrahimi/react-aptor/issues). | ||
| ### [Fabric.js](http://fabricjs.com) | ||
| <a href="https://codesandbox.io/s/react-aptor--fabric-hp50c" title="codesandbox | fabric.js"> | ||
| <img src="https://i.stack.imgur.com/GLnt7.png" width="150"> | ||
| </a> | ||
| <a href="https://codesandbox.io/s/react-aptor--quill-iqwcd" title="codesandbox | quill.js"> | ||
| <img src="https://i.stack.imgur.com/wVBVM.png" width="150"> | ||
| </a> | ||
| | ||
| <a href="https://github.com/amirHossein-Ebrahimi/raptor-howler" title="github | react-howler"> | ||
| <img src="https://raw.githubusercontent.com/amirHossein-Ebrahimi/raptor-howler/master/doc/assets/logo.svg" width="150"> | ||
| </a> | ||
| > Fabric.js is a powerful and simple. Javascript HTML5 canvas library. <img src="https://img.shields.io/github/stars/fabricjs/fabric.js?style=social" /> > <a href="https://codesandbox.io/s/re act-aptor--fabric-hp50c"><img src="https://codesandbox.io/static/img/play-codesandbox.svg"></a> | ||
| <a href="https://stackblitz.com/edit/react-aptor-rivejs" title="stackblitz | rive.js"> | ||
| <img src="https://i.stack.imgur.com/SYdgf.png" width="150"> | ||
| </a> | ||
| ### [Rive.js](https://rive.app) | ||
| <a href="https://codesandbox.io/s/react-aptor--howler-4o8t4" title="codesandbox | howler.js"> | ||
| <img src="https://i.stack.imgur.com/bmvAc.png" width="150" height="150"> | ||
| </a> | ||
| > Create and ship beautiful animations to any platform. <img src="https://img.shields.io/github/stars/rive-app/rive-wasm?style=social" /> > <a href="https://stackblitz.com/edit/react-aptor-rivejs"><img width="165" src="https://developer.stackblitz.com/img/logo.svg"></a> | ||
| ### [Howler.js](https://howlerjs.com) | ||
| > Audio library for the modern web. <img src="https://img.shields.io/github/stars/goldfire/howler.js?style=social" /> > <a href="https://codesandbox.io/s/react-aptor--howler-4o8t4"><img src="https://codesandbox.io/static/img/play-codesandbox.svg"></a> | ||
| ### [Reveal.js](https://revealjs.com) | ||
| > HTML presentation framework create fully featured and beautiful presentations. <img src="https://img.shields.io/github/stars/hakimel/reveal.js?style=social" /> > <a href="https://codesandbox.io/s/react-aptor--reveal-dwrke"><img src="https://codesandbox.io/static/img/play-codesandbox.svg"></a> | ||
| <p align="center"> | ||
| <a href="./doc/samples.md"> ⭐ SEE ALL SAMPLES 🌟</a> | ||
| </p> |
@@ -13,7 +13,7 @@ import { useEffect, useImperativeHandle, useState, useRef, RefObject, useMemo, Ref } from 'react'; | ||
| export interface AptorConfiguration<T> { | ||
| export interface AptorConfiguration<T, P = any> { | ||
| getAPI: GetAPI<T>; | ||
| instantiate: Instantiate<T>; | ||
| destroy?: Destroy<T>; | ||
| params?: any; | ||
| params?: P; | ||
| } | ||
@@ -28,5 +28,5 @@ | ||
| */ | ||
| export default function useAptor<T>( | ||
| export default function useAptor<T, P = any>( | ||
| ref: Ref<APIObject>, | ||
| configuration: AptorConfiguration<T>, | ||
| configuration: AptorConfiguration<T, P>, | ||
| deps: any[] = [] | ||
@@ -33,0 +33,0 @@ ): RefObject<HTMLElement> { |
No alert changes
Improved metrics
- Total package byte prevSize
- increased by0.79%
23511
- Number of lines in readme file
- increased by3.43%
392
No dependency changes