@jaredwray/fumanchu 2.1.0 → 3.0.1

package/README.md

@@ -1,4 +1,4 @@
-![Fumanchu](logo.png "Fumanchu")
+![Fumanchu](site/logo.svg "Fumanchu")
 
 
 # fumanchu
@@ -12,63 +12,95 @@ Handlebars + Helpers Together
 
 [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 in your nodejs as it is a drop in replacement when using handlebars directly.
 
-## Table of Contents
+We plan to make significant changes over time with this project such as the following:
+- **(Completed)** Remove all dependencies on `handlebars-helpers` and maintain all helpers in this project
+- **(Completed)** Migration to `vitest` as a testing framework
+- **(Completed)** Migration to `xo` as a linting framework
+- **(In Progress)** Migrate to Typescript with full typing support
+- **(In Progress)** Replace module dependencies that are no longer supported with supported ones
+- Migration to ESM and CJS support using cross compatible code
+- Move to better documentation and examples where it makes sense
+- Add in browser support via CDN (this will remove the nodejs specific helpers)
+
+# Breaking Changes from v2 to v3
+
+Because of the complexity in the legacy helpers library we have moved to exporting the libraries and a helper function to make it easier to use. Here are the exports:
+
+- `handlebars` - This is an instance of handlebars library without any helpers. It is the same as calling `Handlebars.create()`
+- `helpers` - This is a function that takes an object with a `handlebars` key and adds all the helpers to the handlebars instance. This is the same as calling `helpers({ handlebars: handlebars })`
+- `createHandlebars` - This is an async function that returns a handlebars instance with all the helpers added. This is the same as calling `helpers({ handlebars: handlebars })` but async.
+- `Handlebars` - This is the handlebars library itself. It is the same as calling `require('handlebars')`
+
+Please see the examples below for how to use the library.
+
+# Table of Contents
 * [Using in Nodejs](#using-in-nodejs)
 * [Just using Handlebar Helpers](#using-handlebars-helpers)
 * [Helpers](#helpers)
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
 
-## Usage Nodejs
+
+# Usage Nodejs
 
 ```bash
 npm install @jaredwray/fumanchu --save
 ```
 
 ```javascript
-var handlebars = require('@jaredwray/fumanchu');
+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` via destructuring:
+If using it with es6 you can access `handlebars` and `helpers`:
 
 ```javascript
-import handlebars from '@jaredwray/fumanchu';
+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)**:
+
+```javascript
+import {createHandlebars} from '@jaredwray/fumanchu';
+const handlebars = await createHandlebars(); //this will return a handlebars instance with all 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>
+```
+
 It's just that easy! No need to add Handlebars to your project, it's already included.
 
-## Using Handlebars Helpers
+# Using Handlebars Helpers
 
 If you only want to use handlebar helpers you can easily do that by doing the following:
 
 ```javascript
-var helpers = require('@jaredwray/fumanchu').handlebarHelpers;
+var {helpers} = require('@jaredwray/fumanchu');
 var handlebars = require('handlebars');
 helpers({ handlebars: handlebars });
 var fn = handlebars.compile('{{add value 5}}');
-console.log(fn);
+console.log(fn); // 10
 ```
 
 If using it with es6 you can access `helpers` via destructuring:
 
 ```javascript
-import fumanchu, {handlebarHelpers} from '@jaredwray/fumanchu';
+import {helpers} from '@jaredwray/fumanchu';
 import handlebars from 'handlebars';
-handlebarHelpers({ handlebars: handlebars });
+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);
+console.log(html); // <p>Foo is bar</p>
 ```
 
-Notice that in this scenario you are accessing helpers via `helpers` from `fumanchu` instead of just using handlebars via fumanchu directly.
-
-## Helpers
+# Helpers
 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.
 
 ## Categories
@@ -96,7 +128,7 @@ Currently **189 helpers** in **20 categories**:
 * **[string](#string)** ([code](lib/string.js) | [unit tests](test/string.js))
 * **[url](#url)** ([code](lib/url.js) | [unit tests](test/url.js))
 
-## All helpers
+# All helpers
 
 ### [array helpers](#array)
 
@@ -3066,6 +3098,8 @@ Generate a random number
 ## 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`.
 
+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`.
+
 ## License and Copyright
 [MIT](LICENSE) and codebase after 2023 will be copyright of Jared Wray.
 

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import * as HandlebarsLib from 'handlebars';
+
+declare enum HelperRegistryCompatibility {
+    NODEJS = "nodejs",
+    BROWSER = "browser"
+}
+type HelperFilter = {
+    name?: string;
+    category?: string;
+    compatibility?: HelperRegistryCompatibility;
+};
+
+/**
+ * Handlebars library not initiated with helpers
+ * @type {Handlebars}
+ */
+declare const Handlebars: typeof HandlebarsLib;
+/**
+ * Fumanchu Handlebars instance not initiated with helpers
+ * @type {Handlebars}
+ */
+declare const handlebars: typeof HandlebarsLib;
+/**
+ * Fumanchu Handlebars helpers
+ */
+declare const helpers: {
+    (groups: any, options: any): any;
+    utils: any;
+};
+/**
+ * Create a new Handlebars instance with Fumanchu helpers
+ * @returns {Promise<Handlebars>}
+ */
+declare function createHandlebars(): Promise<typeof HandlebarsLib>;
+/**
+ * @typedef {Object} FumanchuCachingOptions
+ * @property {number|string} [ttl] - Time to Live - If you set a number it is miliseconds, if you set a string it is a human-readable
+ * format such as `1s` for 1 second or `1h` for 1 hour. Setting undefined means that it will use the default time-to-live. If both are
+ * undefined then it will not have a time-to-live.
+ * @property {boolean} [useClone] - If true, it will clone the value before returning it. If false, it will return the value directly. Default is true.
+ * @property {number} [lruSize] - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0.
+ * @property {number} [checkInterval] - The interval to check for expired items. If set to 0, it will not check for expired items. Default is 0.
+ */
+type FumanchuCachingOptions = {
+    ttl?: number | string;
+    useClone?: boolean;
+    lruSize?: number;
+    checkInterval?: number;
+};
+type FumanchuOptions = {
+    handlebars?: typeof HandlebarsLib;
+    helpers?: Record<string, Function>;
+    name?: string | string[];
+    include?: HelperFilter[];
+    exclude?: HelperFilter[];
+    caching?: boolean | FumanchuCachingOptions;
+};
+/**
+ * Will return a Handlebars instance with Fumanchu helpers (experimental)
+ * @returns {Handlebars} Handlebars instance with helpers
+ */
+declare function fumanchu(options?: FumanchuOptions): typeof HandlebarsLib;
+
+export { type FumanchuCachingOptions, type FumanchuOptions, Handlebars, createHandlebars, fumanchu, handlebars, helpers };