@jaredwray/fumanchu 3.1.3 → 4.0.0

package/README.md

@@ -10,11 +10,12 @@ Handlebars + Helpers Together
 [![GitHub license](https://img.shields.io/github/license/jaredwray/fumanchu)](https://github.com/jaredwray/fumanchu/blob/master/LICENSE)
 [![npm](https://img.shields.io/npm/dm/@jaredwray/fumanchu)](https://npmjs.com/package/@jaredwray/fumanchu)
 
-[Handlebars](https://github.com/handlebars-lang/handlebars.js) + [Handlebars-helpers](https://github.com/helpers/handlebars-helpers) (helpers are now maintained in this project) combined into a single package. Easily use it as a drop in replacement when using handlebars directly. More than 180 Handlebars helpers in ~20 categories. Helpers can be used with Assemble, Generate, Verb, Ghost, gulp-handlebars, grunt-handlebars, consolidate, or any node.js/Handlebars project. Currently **189 helpers** in **20 categories**! 🎉
+[Handlebars](https://github.com/handlebars-lang/handlebars.js) + [Handlebars-helpers](https://github.com/helpers/handlebars-helpers) (helpers are now maintained in this project) combined into a single package. Easily use it as a drop in replacement when using handlebars directly. More than 160 Handlebars helpers in ~20 categories. Helpers can be used with Assemble, Generate, Verb, Ghost, gulp-handlebars, grunt-handlebars, consolidate, or any node.js/Handlebars project. Currently **189 helpers** in **20 categories**! 🎉
 
 # Table of Contents
 * [Using in Nodejs](#using-in-nodejs)
 * [Just using Handlebar Helpers](#using-handlebars-helpers)
+* [Migrating from v3 to v4](#migrating-from-v3-to-v4)
 * [Helpers](https://fumanchu.org/docs/helpers/)
   * [array](https://fumanchu.org/docs/helpers/array/)
   * [code](https://fumanchu.org/docs/helpers/code/)
@@ -46,29 +47,11 @@ Handlebars + Helpers Together
 npm install @jaredwray/fumanchu --save
 ```
 
-```javascript
-var {handlebars, helpers} = require('@jaredwray/fumanchu');
-helpers({ handlebars: handlebars });
-var template = handlebars.compile('{{#if (eq foo "bar")}}<p>Foo is bar</p>{{/if}}');
-var html = template({foo: 'bar'});
-console.log(html);
-```
-
-If using it with es6 you can access `handlebars` and `helpers`:
-
-```javascript
-import {handlebars, helpers} from '@jaredwray/fumanchu';
-helpers({ handlebars: handlebars });
-const template = handlebars.compile('{{#if (eq foo "bar")}}<p>Foo is bar</p>{{/if}}');
-const html = template({foo: 'bar'});
-console.log(html);
-```
-
-If you want to just get an instance of handlebars via `createHandlebars` you can do the following **(it is async)**:
+To use Handlebars with all the helpers:
 
 ```javascript
-import {createHandlebars} from '@jaredwray/fumanchu';
-const handlebars = await createHandlebars(); //this will return a handlebars instance with all helpers
+import {fumanchu} from '@jaredwray/fumanchu';
+const handlebars = fumanchu(); // this will return handlebars with all the helpers
 const template = handlebars.compile('{{#if (eq foo "bar")}}<p>Foo is bar</p>{{/if}}');
 const html = template({foo: 'bar'});
 console.log(html); // <p>Foo is bar</p>
@@ -80,17 +63,6 @@ It's just that easy! No need to add Handlebars to your project, it's already inc
 
 If you only want to use handlebar helpers you can easily do that by doing the following:
 
-```javascript
-var {helpers} = require('@jaredwray/fumanchu');
-var handlebars = require('handlebars');
-var helpersFunction = await helpers();
-helpersFunction({ handlebars: handlebars });
-var fn = handlebars.compile('{{add value 5}}');
-console.log(fn); // 10
-```
-
-If using it with es6 you can access `helpers` via destructuring:
-
 ```javascript
 import {helpers} from '@jaredwray/fumanchu';
 import handlebars from 'handlebars';
@@ -101,10 +73,53 @@ const html = template({foo: 'bar'});
 console.log(html); // <p>Foo is bar</p>
 ```
 
-## How to Contribute
-clone the repository locally and run 'npm i' in the root. Now that you've set up your workspace, you're ready to contribute changes to the `fumanchu` repository you can refer to the [CONTRIBUTING](CONTRIBUTING.md) guide. If you have any questions please feel free to ask by creating an issue and label it `question`.
+If using it with es6 you can access `handlebars` and `helpers`:
 
-To test the legacy helpers, you can run `npm run test:legacy` to run the tests. If you want to test the new helpers, you can run `npm run test`.
+```javascript
+import {handlebars, helpers} from '@jaredwray/fumanchu';
+helpers({ handlebars: handlebars });
+const template = handlebars.compile('{{#if (eq foo "bar")}}<p>Foo is bar</p>{{/if}}');
+const html = template({foo: 'bar'});
+console.log(html);
+```
+
+# Using the Helper Registry
+
+The helper registry allows you to manage and use Handlebars helpers more easily. You can register new helpers, filter existing ones, and access them in your templates.
+
+```js
+import { HelperRegistry, handlebars } from '@jaredwray/fumanchu';
+
+const registry = new HelperRegistry();
+registry.register('eq', (a, b) => a === b);
+registry.register('if', (condition, template) => condition ? template() : '');
+const hbs = handlebars;
+registry.load(hbs); // Load all helpers into Handlebars
+```
+
+If you want to do filtering you can use the `HelperFilter` on `load`:
+
+```js
+import { HelperRegistry, handlebars } from '@jaredwray/fumanchu';
+
+const registry = new HelperRegistry();
+registry.register('eq', (a, b) => a === b);
+registry.register('if', (condition, template) => condition ? template() : '');
+const hbs = handlebars;
+registry.load(hbs, { names: ['if']}); // Load the helpers into Handlebars
+```
+
+In addition, we have made the helper functions have a compatibility such as `HelperRegistryCompatibility.NODEJS` or `HelperRegistryCompatibility.BROWSER`. This will allow you to filter out based on your environment!
+
+# Migrating from v3 to v4
+
+We have made some breaking changes in v4:
+* We no longer support the legacy helpers that were in this project as we have migrated to a new helper system.
+* `createHandlebars` is now deprecated in favor of just using `fumanchu()` and no more needing async.
+* The `FumanchuOptions` has been changed on filtering and also now fully supported with `fumanchu()`
+
+## How to Contribute
+Clone the repository locally refer to the [CONTRIBUTING](CONTRIBUTING.md) guide. If you have any questions please feel free to ask by creating an issue and label it `question`.
 
 ## License and Copyright
 [MIT](LICENSE) and codebase after 2023 will be copyright of Jared Wray.