extending transform with parent (#15)

Author: vitaly-t

src/parser.ts

@@ -39,7 +39,7 @@ export function createFormatter(base: IFormatter) {
         return text.replace(formatRegEx, (...args: string[]) => {
             const prop = args[4]; // property name
             const filters = args[5]; // filters, if specified
-            let {exists, value} = resolveProperty(prop, params);
+            let {exists, value, parent} = resolveProperty(prop, params);
             if (!exists) {
                 if (typeof base.getDefaultValue !== 'function') {
                     throw new Error(`Property ${JSON.stringify(prop)} does not exist`);
@@ -61,7 +61,7 @@ export function createFormatter(base: IFormatter) {
                             throw new Error(`Filter ${JSON.stringify(fName)} not recognized`);
                         }
                         const decodedArgs = typeof f.decodeArguments === 'function' ? f.decodeArguments(args) : args.map(a => decodeFilterArg(a));
-                        return f.transform(p, decodedArgs);
+                        return f.transform(p, decodedArgs, parent);
                     }, value);
             }
             return base.format(value);

src/protocol.ts

@@ -17,6 +17,13 @@ export interface IFilter<T = any, R = any> {
      * By default, each argument is HTML-decoded, unless override
      * {@link decodeArguments} is implemented.
      *
+     * @param parent
+     * Container for the resolved property - value/property immediately preceding it (in the resolution chain).
+     *
+     * For example, for a simple property reference (not a nested one), the container is the formatting object itself.
+     *
+     * It is `undefined` when the property chain contains only `this`, because in that case there is no container.
+     *
      * @returns
      * Result of the value transformation.
      *
@@ -45,7 +52,7 @@ export interface IFilter<T = any, R = any> {
      *
      * // Both approaches will work the same as the example above.
      */
-    transform(value: T, args: string[]): R;
+    transform(value: T, args: string[], parent: any): R;
 
     /**
      * Optional override for decoding filter arguments.

src/resolver.ts

@@ -9,9 +9,16 @@ export interface IProperty {
     exists: boolean;
 
     /**
-     * The resolved value, set only when 'exists' = true
+     * The resolved value, set only when 'exists' = true.
      */
     value?: any;
+
+    /**
+     * Container for the resolved property - value/property immediately preceding it (in the resolution chain).
+     *
+     * It is set only when 'exists' = true.
+     */
+    parent?: any;
 }
 
 /**
@@ -21,7 +28,7 @@ export interface IProperty {
  */
 export function resolveProperty(prop: string, obj: { [key: string]: any }): IProperty {
     const names = prop.split('.').filter(a => a);
-    let exists = false, value = obj;
+    let exists = false, value = obj, parent = undefined;
     for (const [i, n] of names.entries()) {
         if (!i && n === 'this') {
             exists = true;
@@ -31,7 +38,8 @@ export function resolveProperty(prop: string, obj: { [key: string]: any }): IPro
             return {exists: false};
         }
         exists = true;
+        parent = value;
         value = value[n];
     }
-    return exists ? {exists, value} : {exists};
+    return exists ? {exists, value, parent} : {exists};
 }

test/parser.spec.ts

@@ -100,33 +100,37 @@ describe('createFormatter', () => {
     describe('for filter arguments', () => {
         it('must handle empty args', () => {
             const cb = jest.spyOn(fullFormatter.filters.json, 'transform');
-            fullFormat('${value|json:}', {value: 'message'});
-            expect(cb).toHaveBeenCalledWith('message', ['']);
-
-            fullFormat('${value|json:::Hello World!}', {value: 'message'});
-            expect(cb).toHaveBeenCalledWith('message', ['', '', 'Hello World!']);
+            const obj = {value: 'message'};
+            fullFormat('${value|json:}', obj);
+            expect(cb).toHaveBeenCalledWith('message', [''], obj);
+            fullFormat('${value|json:::Hello World!}', obj);
+            expect(cb).toHaveBeenCalledWith('message', ['', '', 'Hello World!'], obj);
         });
         it('must resolve numbers', () => {
             const cb = jest.spyOn(fullFormatter.filters.json, 'transform');
-            fullFormat('${value|json: 1: 22.33: -45.678}', {value: 'message'});
-            expect(cb).toHaveBeenCalledWith('message', ['1', '22.33', '-45.678']);
+            const obj = {value: 'message'};
+            fullFormat('${value|json: 1: 22.33: -45.678}', obj);
+            expect(cb).toHaveBeenCalledWith('message', ['1', '22.33', '-45.678'], obj);
         });
         it('must resolve random text with spaces', () => {
             const cb1 = jest.spyOn(fullFormatter.filters.json, 'transform');
             const cb2 = jest.spyOn(fullFormatter, 'getDefaultFilter');
-            fullFormat('${value|object: Hello World! : Where are we? }', {value: 'message'});
-            expect(cb1).toHaveBeenCalledWith('message', ['Hello World!', 'Where are we?']);
+            const obj = {value: 'message'};
+            fullFormat('${value|object: Hello World! : Where are we? }', obj);
+            expect(cb1).toHaveBeenCalledWith('message', ['Hello World!', 'Where are we?'], obj);
             expect(cb2).toHaveBeenCalledWith('object', ['Hello World!', 'Where are we?']);
         });
         it('must decode HTML symbols by default', () => {
             const cb = jest.spyOn(fullFormatter.filters.json, 'transform');
-            fullFormat('${value|json: :}', {value: 'message'});
-            expect(cb).toHaveBeenCalledWith('message', [':']);
+            const obj = {value: 'message'};
+            fullFormat('${value|json: :}', obj);
+            expect(cb).toHaveBeenCalledWith('message', [':'], obj);
         });
         it('must not decode HTML symbols with override present', () => {
             const cb = jest.spyOn(fullFormatter.filters.append, 'transform');
-            fullFormat('${value|append: :}', {value: 'message'});
-            expect(cb).toHaveBeenCalledWith('message', [':']);
+            const obj = {value: 'message'};
+            fullFormat('${value|append: :}', obj);
+            expect(cb).toHaveBeenCalledWith('message', [':'], obj);
         });
     });
 });

test/resolver.spec.ts

@@ -3,12 +3,13 @@ import {resolveProperty} from '../src/resolver';
 describe('resolveProperty', () => {
     it('must resolve "this"', () => {
         const obj = {prop: 123};
-        expect(resolveProperty('this', obj)).toStrictEqual({exists: true, value: obj});
-        expect(resolveProperty('this.prop', obj)).toStrictEqual({exists: true, value: obj.prop});
+        expect(resolveProperty('this', obj)).toStrictEqual({exists: true, value: obj, parent: undefined});
+        expect(resolveProperty('this.prop', obj)).toStrictEqual({exists: true, value: obj.prop, parent: obj});
     });
     it('must resolve deep properties', () => {
-        const obj = {a: {b: {c: {d: 123}}}};
-        expect(resolveProperty('a.b.c.d', obj)).toEqual({exists: true, value: 123});
+        const parent = {d: 123};
+        const obj = {a: {b: {c: parent}}};
+        expect(resolveProperty('a.b.c.d', obj)).toEqual({exists: true, value: 123, parent});
     });
     it('it must handle missing properties', () => {
         const obj = {a: {b: null}};
@@ -20,7 +21,8 @@ describe('resolveProperty', () => {
         expect(resolveProperty('...', {})).toEqual({exists: false});
     });
     it('must handle array indexes', () => {
-        expect(resolveProperty('a.1.value', {a: [0, {value: 123}]})).toEqual({exists: true, value: 123});
+        const obj = {value: 123};
+        expect(resolveProperty('a.1.value', {a: [0, obj]})).toEqual({exists: true, value: 123, parent: obj});
     });
     it('must handle array indexes outside range', () => {
         expect(resolveProperty('a.2', {a: [0, 1]})).toEqual({exists: false});