@jaredwray/fumanchu 4.5.1 → 4.6.0

package/README.md

@@ -7,7 +7,8 @@ Handlebars + Helpers Together
 [![tests](https://github.com/jaredwray/fumanchu/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/fumanchu/actions/workflows/tests.yaml)
 [![codecov](https://codecov.io/gh/jaredwray/fumanchu/graph/badge.svg?token=gtYw78huva)](https://codecov.io/gh/jaredwray/fumanchu)
 [![npm version](https://img.shields.io/npm/v/@jaredwray/fumanchu.svg)](https://npmjs.com/package/@jaredwray/fumanchu)
-[![GitHub license](https://img.shields.io/github/license/jaredwray/fumanchu)](https://github.com/jaredwray/fumanchu/blob/master/LICENSE)
+[![NPM License](https://img.shields.io/npm/l/%40jaredwray%2Ffumanchu)
+](https://github.com/jaredwray/fumanchu/blob/main/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 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**! 🎉
@@ -39,6 +40,7 @@ Handlebars + Helpers Together
   * [string](https://fumanchu.org/docs/string/)
   * [url](https://fumanchu.org/docs/url/)
   * [utils](https://fumanchu.org/docs/utils/)
+* [Caching](#caching)
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
 
@@ -112,6 +114,53 @@ 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!
 
+# Caching
+
+When caching is enabled, Fumanchu wraps the Handlebars `compile()` method to cache compiled template functions using [@cacheable/memory](https://github.com/jaredwray/cacheable/tree/main/packages/memory). If you compile the same template string multiple times, the cached version is returned instead of recompiling. The returned Handlebars instance is fully compatible -- caching is transparent to your existing code.
+
+The `caching` option accepts three types:
+- `boolean` -- `true` enables caching with defaults, `false` disables it
+- `CacheableMemory` -- a pre-configured instance from `@cacheable/memory`
+- `CacheableMemoryOptions` -- an options object passed to `CacheableMemory` (supports `ttl`, `lruSize`, `checkInterval`, etc.)
+
+## Enable caching with default settings
+
+```javascript
+import { fumanchu } from '@jaredwray/fumanchu';
+const handlebars = fumanchu({ caching: true });
+
+const template = handlebars.compile('Hello {{name}}!');
+template({ name: 'World' }); // compiles and caches
+
+const template2 = handlebars.compile('Hello {{name}}!');
+// returns the cached compiled function -- no recompilation
+```
+
+## Pass caching options
+
+```javascript
+import { fumanchu } from '@jaredwray/fumanchu';
+const handlebars = fumanchu({
+  caching: {
+    ttl: '1h',         // Time-to-live in ms or human-readable string like '1h'
+    lruSize: 500,      // LRU cache size limit (0 = unlimited)
+    checkInterval: 0,  // Interval to check for expired items in ms (0 = disabled)
+  },
+});
+```
+
+## Pass a pre-configured `CacheableMemory` instance
+
+This is useful if you want to share a cache across multiple Fumanchu instances or manage the cache lifecycle yourself:
+
+```javascript
+import { fumanchu, CacheableMemory } from '@jaredwray/fumanchu';
+const cache = new CacheableMemory({ ttl: '1h', lruSize: 1000, useClone: false });
+
+const hbs1 = fumanchu({ caching: cache });
+const hbs2 = fumanchu({ caching: cache }); // shares the same cache as hbs1
+```
+
 ## 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`.
 

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CacheableMemory: () => import_memory.CacheableMemory,
   Handlebars: () => Handlebars3,
   HelperRegistry: () => HelperRegistry,
   createHandlebars: () => createHandlebars,
@@ -38,6 +39,7 @@ __export(index_exports, {
   helpers: () => helpers21
 });
 module.exports = __toCommonJS(index_exports);
+var import_memory = require("@cacheable/memory");
 var import_handlebars3 = __toESM(require("handlebars"), 1);
 
 // src/helpers/array.ts
@@ -3167,10 +3169,35 @@ function fumanchu(options2) {
     handlebars2.registerPartial(import_handlebars3.default.partials);
   }
   registry.load(handlebars2);
+  if (options2?.caching) {
+    let cache;
+    if (options2.caching instanceof import_memory.CacheableMemory) {
+      cache = options2.caching;
+    } else if (typeof options2.caching === "object") {
+      cache = new import_memory.CacheableMemory({
+        useClone: false,
+        ...options2.caching
+      });
+    } else {
+      cache = new import_memory.CacheableMemory({ useClone: false });
+    }
+    const originalCompile = handlebars2.compile.bind(handlebars2);
+    handlebars2.compile = (input, compileOptions) => {
+      const key = compileOptions ? input + JSON.stringify(compileOptions) : String(input);
+      const cached = cache.get(key);
+      if (cached) {
+        return cached;
+      }
+      const compiled = originalCompile(input, compileOptions);
+      cache.set(key, compiled);
+      return compiled;
+    };
+  }
   return handlebars2;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CacheableMemory,
   Handlebars,
   HelperRegistry,
   createHandlebars,

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { CacheableMemory, CacheableMemoryOptions } from '@cacheable/memory';
+export { CacheableMemory, CacheableMemoryOptions } from '@cacheable/memory';
 import HandlebarsLib from 'handlebars';
 
 type Helper = {
@@ -88,25 +90,10 @@ declare function helpers(options: HelpersOptions): void;
  * @deprecated Will be deprecated in future versions, use `fumanchu()` instead.
  */
 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;
     filter?: HelperFilter;
-    caching?: boolean | FumanchuCachingOptions;
+    caching?: boolean | CacheableMemory | CacheableMemoryOptions;
 };
 /**
  * Will return a Handlebars instance with Fumanchu helpers (experimental)
@@ -115,4 +102,4 @@ type FumanchuOptions = {
  */
 declare function fumanchu(options?: FumanchuOptions): typeof HandlebarsLib;
 
-export { type FumanchuCachingOptions, type FumanchuOptions, Handlebars, type HelperFilter, HelperRegistry, type HelpersOptions, createHandlebars, fumanchu, handlebars, helpers };
+export { type FumanchuOptions, Handlebars, type HelperFilter, HelperRegistry, type HelpersOptions, createHandlebars, fumanchu, handlebars, helpers };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { CacheableMemory, CacheableMemoryOptions } from '@cacheable/memory';
+export { CacheableMemory, CacheableMemoryOptions } from '@cacheable/memory';
 import HandlebarsLib from 'handlebars';
 
 type Helper = {
@@ -88,25 +90,10 @@ declare function helpers(options: HelpersOptions): void;
  * @deprecated Will be deprecated in future versions, use `fumanchu()` instead.
  */
 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;
     filter?: HelperFilter;
-    caching?: boolean | FumanchuCachingOptions;
+    caching?: boolean | CacheableMemory | CacheableMemoryOptions;
 };
 /**
  * Will return a Handlebars instance with Fumanchu helpers (experimental)
@@ -115,4 +102,4 @@ type FumanchuOptions = {
  */
 declare function fumanchu(options?: FumanchuOptions): typeof HandlebarsLib;
 
-export { type FumanchuCachingOptions, type FumanchuOptions, Handlebars, type HelperFilter, HelperRegistry, type HelpersOptions, createHandlebars, fumanchu, handlebars, helpers };
+export { type FumanchuOptions, Handlebars, type HelperFilter, HelperRegistry, type HelpersOptions, createHandlebars, fumanchu, handlebars, helpers };

package/dist/index.js

@@ -1,4 +1,7 @@
 // src/index.ts
+import {
+  CacheableMemory
+} from "@cacheable/memory";
 import HandlebarsLib from "handlebars";
 
 // src/helpers/array.ts
@@ -3128,9 +3131,34 @@ function fumanchu(options2) {
     handlebars2.registerPartial(HandlebarsLib.partials);
   }
   registry.load(handlebars2);
+  if (options2?.caching) {
+    let cache;
+    if (options2.caching instanceof CacheableMemory) {
+      cache = options2.caching;
+    } else if (typeof options2.caching === "object") {
+      cache = new CacheableMemory({
+        useClone: false,
+        ...options2.caching
+      });
+    } else {
+      cache = new CacheableMemory({ useClone: false });
+    }
+    const originalCompile = handlebars2.compile.bind(handlebars2);
+    handlebars2.compile = (input, compileOptions) => {
+      const key = compileOptions ? input + JSON.stringify(compileOptions) : String(input);
+      const cached = cache.get(key);
+      if (cached) {
+        return cached;
+      }
+      const compiled = originalCompile(input, compileOptions);
+      cache.set(key, compiled);
+      return compiled;
+    };
+  }
   return handlebars2;
 }
 export {
+  CacheableMemory,
   Handlebars3 as Handlebars,
   HelperRegistry,
   createHandlebars,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jaredwray/fumanchu",
   "description": "Handlebars + Helpers = Fumanchu",
-  "version": "4.5.1",
+  "version": "4.6.0",
   "homepage": "https://github.com/jaredwray/fumanchu",
   "author": "Jared Wray (me@jaredwray.com)",
   "type": "module",
@@ -63,6 +63,7 @@
     "license"
   ],
   "dependencies": {
+    "@cacheable/memory": "^2.0.7",
     "chrono-node": "2.9.0",
     "dayjs": "^1.11.19",
     "ent": "^2.2.2",