url-templates 1.0.3 → 1.0.4

package/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Validate a template.
- * Returns true or throws a detailed error.
+ * @returns true or throws a detailed error.
  *
  * @throws {TypeError | Error}
  */
@@ -8,30 +8,40 @@ declare function isUrlTemplate(template: string): boolean;
 
 /**
  * Inspect a template.
- * Returns the parsed AST.
+ * @returns the parsed AST.
  */
 declare function inspect(template: string): any[];
 
+/**
+ * Expand the compiled template by given vars.
+ * @param  vars - the object containing expansion variables.
+ * @param  callback - optional function that receives the current key and should return a replacement for current value.
+ * @returns the expanded template.
+ */
+declare function expand(vars: any, callback?: { key: string }): string
+
 /**
  * Parse and validate a template.
- * Returns an object with an expand() method.
+ * @returns an object with an expand() method.
  *
  * @throws {TypeError | Error}
  */
-declare function parseTemplate(template: string): { expand(vars?: any): string };
+declare function parseTemplate(template: string): { expand: typeof expand };
 
 /**
  * Compile a template without validation.
- * Returns an object with an expand() method.
+ * @returns an object with an expand() method.
  */
-declare function compile(template: string): { expand(vars?: any): string };
+declare function compile(template: string): { expand: typeof expand };
 
 /**
  * Recursively compile a template without validation.
- * The start template must be a vars[key].
- * Returns the recursively compiled and expanded template.
+ * @param  vars - the object containing expansion variables.
+ * @param  templateKey - starter template key, must be a vars[key].
+ * @param  callback - optional function that receives the current key and should return a replacement for current value.
+ * @returns the recursively compiled and expanded template.
  */
-declare function recursiveCompile(vars: object, templateKey: string): string;
+declare function recursiveCompile(vars: object, templateKey: string, callback?: { key: string } ): string;
 
 declare const urlTemplates: {
     isUrlTemplate: typeof isUrlTemplate;

package/index.js

@@ -55,7 +55,7 @@ function isUrlTemplate(template, inspect) {
 function parseTemplate(template, validate) {
     if (validate) isUrlTemplate(template);
     return {
-        expand: (vars = {}) =>
+        expand: (vars = {}, callback) =>
             template.replace(/([^\{\}]+)|\{([^\{\}])([^\{\}]*)\}/g, (match, literal, first, expression) => {
                 if (first + expression) {
                     const values = [];
@@ -64,7 +64,7 @@ function parseTemplate(template, validate) {
                     expression.split(/,/g).forEach((variable) => {
                         const match = /(?<key>[^:\*]*)(?::(?<length>\d+)|(?<explode>\*))?/.exec(variable).groups;
                         const key = match.key;
-                        const value = vars[key];
+                        const value = typeof callback === 'function' ? callback(key) : vars[key];
                         if (!isDefined(value)) defined--;
                         if (isDefined(value) && value !== '') {
                             if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
@@ -115,12 +115,12 @@ function parseTemplate(template, validate) {
     };
 }
 // recursive compile
-function recursiveCompile(vars, key) {
+function recursiveCompile(vars, key, callback) {
     let prev;
     let result = vars[key];
     do {
         prev = result;
-        result = decodeURIComponent(parseTemplate(result).expand(vars));
+        result = decodeURIComponent(parseTemplate(result).expand(vars, callback));
     } while (result !== prev);
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "url-templates",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A url-template validator, expander and inspector as defined by RFC 6570",
   "keywords": [
     "url",

package/readme.md

@@ -48,7 +48,7 @@ try {
 ```
 
 **Note:**
-Same as with `isUrlTemplate`, but if valid returns the parsed `AST` instead of `true`.
+- Same as with `isUrlTemplate`, but if valid returns the parsed `AST` instead of `true`.
 
 ### Expansion with validation
 
@@ -62,7 +62,7 @@ try {
 ```
 
 **Note:**
-If valid returns the `expand(vars)` function which returns the expanded `url-template`. Otherwise, it throws an `error`. The `expand` function also throws `error` if `limit` is defined on `objects` (`isUrlTemplate` function cannot know that without runtime vars).
+- If valid returns the `expand(vars)` function which returns the expanded `url-template`. Otherwise, it throws an `error`. The `expand` function also throws `error` if `limit` is defined on `objects` (`isUrlTemplate` function cannot know that without runtime vars).
 
 ### Expansion without validation
 
@@ -74,7 +74,7 @@ console.log(compile('/undefined{id}').expand({ id: undefined })); // returns '/u
 ```
 
 **Note:**
-Returns a usable expander without validation for cases where validation is done elsewhere, or for the cases where some sort of postprocessing will follow. A good example of postprocessing is described next:
+- Returns a usable expander without validation for cases where validation is done elsewhere, or for the cases where some sort of postprocessing will follow. A good example of postprocessing is described next:
 
 ### Multi pass expansion without validation
 
@@ -101,7 +101,21 @@ console.log(compile(firstPass).expand(vars2)); // returns '[1,2,3]';
 ```
 
 **Important Note:**
-The first pass will preserve the `{bar,baz}` expression only if the supplied variable has **none** of its members. This method can also be used to preserve quantifiers like `{1,4}` in regular expressions.
+- The first pass will preserve the `{bar,baz}` expression only if the supplied variable has **none** of its members. This method can also be used to preserve quantifiers like `{1,4}` in regular expressions.
+
+**Example 3 (transform with callback)**
+
+```js title="js"
+const { compile } = require('url-templates');
+const vars1 = { foo: 1 };
+const vars2 = { bar: 2, baz: 3 };
+const firstPass = decodeURIComponent(compile('[{foo},{bar,baz}]').expand(vars1));
+console.log(firstPass); // returns '[1,{bar,baz}]';
+console.log(compile(firstPass).expand(vars2, (key) => key === 'baz' ? vars2[key] * 10 : vars2[key])); // returns '[1,2,30]';
+```
+
+**Note:**
+- The optional `callback` function argument is present on each `expand` function.
 
 ### Recursively compile and expand without validation
 
@@ -122,3 +136,11 @@ const { recursiveCompile } = require('url-templates');
 const vars = { start: '[{foo},{boo}]', boo: '{bar,baz}', foo: 1, bar: 2, baz: 3 };
 console.log(recursiveCompile(vars, 'start')); // returns '[1,2,3]';
 ```
+
+**Example 3 (transform with callback)**
+
+```js title="js"
+const { recursiveCompile } = require('url-templates');
+const vars = { start: '[{foo},{bar,baz}]', foo: 1, bar: 2, baz: 3 };
+console.log(recursiveCompile(vars, 'start', (key) => vars[key] * 2)); // returns '[2,4,6]';
+```