From d80406a508c9fae93b16d9b5201a4a73b7301c18 Mon Sep 17 00:00:00 2001
From: Lukas Siemon <lukas.siemon@blackflux.com>
Date: Tue, 14 Jun 2022 21:40:30 -0700
Subject: [PATCH 1/4] fix: minor refactor / readme update

---
 README.md                      | 33 ++++++++++++++++++++++++++++-----
 src/core/find.js               |  2 +-
 test/readme/README.template.md | 29 ++++++++++++++++++++++++-----
 3 files changed, 53 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index d23e4d26..ff02245c 100644
--- a/README.md
+++ b/README.md
@@ -482,10 +482,16 @@ objectScan(['**'], {
 Type: `function`<br>
 Default: `undefined`
 
-When defined, this function is called before traversal as `beforeFn(state = { haystack, context })`
-and `state.haystack` is subsequently traversed using `state.context`.
+When defined, this function is called before traversal as `beforeFn(state = { haystack, context })`.
 
-If a value other than `undefined` is returned, that value is written to `state.haystack` before traversal.
+If a value other than `undefined` is returned from `beforeFn`,
+that value is written to `state.haystack` before traversal.
+
+The content of `state` can be modified in the function.
+After `beforeFn` has executed, the traversal happens using `state.haystack` and `state.context`.
+
+The content in `state` can be accessed in `afterFn`.
+Note however that the key `result` is being overwritten.
 
 _Examples_:
 <details><summary> <code>['**']</code> <em>(combining haystack and context)</em> </summary>
@@ -522,8 +528,13 @@ Default: `undefined`
 
 When defined, this function is called after traversal as `afterFn(state = { result, haystack, context })`.
 
-If a value other than `undefined` is returned, that value is returned as
-the final result instead of `state.result`.
+Additional information written to `state` in `beforeFn` is available in `afterFn`.
+
+The content of `state` can be modified in the function. In particular the key `state.result` can be updated.
+
+If a value other than `undefined` is returned from `afterFn`, that value is written to `state.result`.
+
+After `beforeFn` has executed, the key `state.result` is returned as the final result.
 
 _Examples_:
 <details><summary> <code>['**']</code> <em>(returning count plus context)</em> </summary>
@@ -550,6 +561,18 @@ objectScan(['**'], {
 // => [ 4 ]
 ```
 </details>
+<details><summary> <code>['**']</code> <em>(pass data from beforeFn to afterFn)</em> </summary>
+
+<!-- eslint-disable no-undef -->
+```js
+const haystack = {};
+objectScan(['**'], {
+  beforeFn: (state) => { state.custom = 7; },
+  afterFn: (state) => state.custom
+})(haystack);
+// => 7
+```
+</details>
 
 #### compareFn
 
diff --git a/src/core/find.js b/src/core/find.js
index f794a2c4..6ec59b53 100644
--- a/src/core/find.js
+++ b/src/core/find.js
@@ -205,7 +205,7 @@ export default (haystack_, searches_, ctx) => {
   if (ctx.afterFn !== undefined) {
     const r = ctx.afterFn(state);
     if (r !== undefined) {
-      return r;
+      state.result = r;
     }
   }
   return state.result;
diff --git a/test/readme/README.template.md b/test/readme/README.template.md
index 45c3bfc6..500bdcb9 100644
--- a/test/readme/README.template.md
+++ b/test/readme/README.template.md
@@ -356,10 +356,16 @@ breakFn: ({ key }) => key === 'a.b'
 Type: `function`<br>
 Default: `undefined`
 
-When defined, this function is called before traversal as `beforeFn(state = { haystack, context })`
-and `state.haystack` is subsequently traversed using `state.context`.
+When defined, this function is called before traversal as `beforeFn(state = { haystack, context })`.
 
-If a value other than `undefined` is returned, that value is written to `state.haystack` before traversal.
+If a value other than `undefined` is returned from `beforeFn`,
+that value is written to `state.haystack` before traversal.
+
+The content of `state` can be modified in the function.
+After `beforeFn` has executed, the traversal happens using `state.haystack` and `state.context`.
+
+The content in `state` can be accessed in `afterFn`.
+Note however that the key `result` is being overwritten.
 
 _Examples_:
 <pre><example>
@@ -385,8 +391,13 @@ Default: `undefined`
 
 When defined, this function is called after traversal as `afterFn(state = { result, haystack, context })`.
 
-If a value other than `undefined` is returned, that value is returned as
-the final result instead of `state.result`.
+Additional information written to `state` in `beforeFn` is available in `afterFn`.
+
+The content of `state` can be modified in the function. In particular the key `state.result` can be updated.
+
+If a value other than `undefined` is returned from `afterFn`, that value is written to `state.result`.
+
+After `beforeFn` has executed, the key `state.result` is returned as the final result.
 
 _Examples_:
 <pre><example>
@@ -406,6 +417,14 @@ afterFn: ({ result }) => result.filter((v) => v > 3)
 rtn: 'value'
 joined: false
 </example></pre>
+<pre><example>
+haystack: {}
+needles: ['**']
+comment: pass data from beforeFn to afterFn
+beforeFn: (state) => { state.custom = 7; }
+afterFn: (state) => state.custom
+joined: false
+</example></pre>
 
 #### compareFn
 

From 916c5095574c9a795a5b637c5a250bc3fa8648a3 Mon Sep 17 00:00:00 2001
From: Lukas Siemon <lukas.siemon@blackflux.com>
Date: Tue, 14 Jun 2022 21:43:46 -0700
Subject: [PATCH 2/4] amend: eslint fix

---
 README.md                      | 2 +-
 test/readme/README.template.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ff02245c..3325bc0e 100644
--- a/README.md
+++ b/README.md
@@ -567,7 +567,7 @@ objectScan(['**'], {
 ```js
 const haystack = {};
 objectScan(['**'], {
-  beforeFn: (state) => { state.custom = 7; },
+  beforeFn: (state) => { /* eslint-disable no-param-reassign */ state.custom = 7; },
   afterFn: (state) => state.custom
 })(haystack);
 // => 7
diff --git a/test/readme/README.template.md b/test/readme/README.template.md
index 500bdcb9..c993c88e 100644
--- a/test/readme/README.template.md
+++ b/test/readme/README.template.md
@@ -421,7 +421,7 @@ joined: false
 haystack: {}
 needles: ['**']
 comment: pass data from beforeFn to afterFn
-beforeFn: (state) => { state.custom = 7; }
+beforeFn: (state) => { /* eslint-disable no-param-reassign */ state.custom = 7; }
 afterFn: (state) => state.custom
 joined: false
 </example></pre>

From 9d277a03577e3d6cd24258795587f019e4c29ed3 Mon Sep 17 00:00:00 2001
From: Lukas Siemon <lukas.siemon@blackflux.com>
Date: Tue, 14 Jun 2022 21:51:42 -0700
Subject: [PATCH 3/4] chore: refactor

---
 src/core/compiler.js                                    | 6 +++---
 src/core/{compiler-iterator.js => compiler/iterator.js} | 2 +-
 src/core/find.js                                        | 2 +-
 src/core/{find-result.js => find/result.js}             | 0
 src/core/parser.js                                      | 4 ++--
 src/core/{ => parser}/ref.js                            | 0
 src/core/{parser-result.js => parser/result.js}         | 4 ++--
 src/core/{ => parser}/wildcard.js                       | 2 +-
 test/core/parser.spec.js                                | 2 +-
 test/core/{ => parser}/wildcard.spec.js                 | 2 +-
 10 files changed, 12 insertions(+), 12 deletions(-)
 rename src/core/{compiler-iterator.js => compiler/iterator.js} (94%)
 rename src/core/{find-result.js => find/result.js} (100%)
 rename src/core/{ => parser}/ref.js (100%)
 rename src/core/{parser-result.js => parser/result.js} (97%)
 rename src/core/{ => parser}/wildcard.js (97%)
 rename test/core/{ => parser}/wildcard.spec.js (94%)

diff --git a/src/core/compiler.js b/src/core/compiler.js
index c36aa9a2..d17cba5b 100644
--- a/src/core/compiler.js
+++ b/src/core/compiler.js
@@ -1,9 +1,9 @@
 /* compile needles to hierarchical map object */
 import parser from './parser.js';
-import iterator from './compiler-iterator.js';
+import iterator from './compiler/iterator.js';
 import { defineProperty } from '../generic/helper.js';
-import { Wildcard } from './wildcard.js';
-import { Ref } from './ref.js';
+import { Wildcard } from './parser/wildcard.js';
+import { Ref } from './parser/ref.js';
 
 const LEAF = Symbol('leaf');
 const markLeaf = (input, match, readonly) => defineProperty(input, LEAF, match, readonly);
diff --git a/src/core/compiler-iterator.js b/src/core/compiler/iterator.js
similarity index 94%
rename from src/core/compiler-iterator.js
rename to src/core/compiler/iterator.js
index b45044e6..540cc2e0 100644
--- a/src/core/compiler-iterator.js
+++ b/src/core/compiler/iterator.js
@@ -1,4 +1,4 @@
-import iterator from '../generic/iterator.js';
+import iterator from '../../generic/iterator.js';
 
 export default (tower, needle, tree, { onAdd, onFin }) => {
   const stack = [[[tower, null]]];
diff --git a/src/core/find.js b/src/core/find.js
index 6ec59b53..fbae9377 100644
--- a/src/core/find.js
+++ b/src/core/find.js
@@ -3,7 +3,7 @@ import {
   hasMatches, matchedBy, isLastLeafMatch,
   getValues, getOrder, getRoots
 } from './compiler.js';
-import Result from './find-result.js';
+import Result from './find/result.js';
 import { toPath } from '../generic/helper.js';
 
 const formatPath = (input, ctx) => (ctx.joined ? toPath(input) : [...input]);
diff --git a/src/core/find-result.js b/src/core/find/result.js
similarity index 100%
rename from src/core/find-result.js
rename to src/core/find/result.js
diff --git a/src/core/parser.js b/src/core/parser.js
index b52ee4a0..180e80e2 100644
--- a/src/core/parser.js
+++ b/src/core/parser.js
@@ -1,5 +1,5 @@
-import { Wildcard } from './wildcard.js';
-import Result from './parser-result.js';
+import { Wildcard } from './parser/wildcard.js';
+import Result from './parser/result.js';
 
 const throwError = (msg, input, context = {}) => {
   throw new Error(Object.entries(context)
diff --git a/src/core/ref.js b/src/core/parser/ref.js
similarity index 100%
rename from src/core/ref.js
rename to src/core/parser/ref.js
diff --git a/src/core/parser-result.js b/src/core/parser/result.js
similarity index 97%
rename from src/core/parser-result.js
rename to src/core/parser/result.js
index 2f0ac17d..ea208e7e 100644
--- a/src/core/parser-result.js
+++ b/src/core/parser/result.js
@@ -1,5 +1,5 @@
-import assert from '../generic/assert.js';
-import { defineProperty } from '../generic/helper.js';
+import assert from '../../generic/assert.js';
+import { defineProperty } from '../../generic/helper.js';
 import { Wildcard } from './wildcard.js';
 import { Ref } from './ref.js';
 
diff --git a/src/core/wildcard.js b/src/core/parser/wildcard.js
similarity index 97%
rename from src/core/wildcard.js
rename to src/core/parser/wildcard.js
index 782127e3..e0f04b41 100644
--- a/src/core/wildcard.js
+++ b/src/core/parser/wildcard.js
@@ -1,4 +1,4 @@
-import { escapeRegex, asRegex } from '../generic/helper.js';
+import { escapeRegex, asRegex } from '../../generic/helper.js';
 
 export const parseWildcard = (str) => {
   let regex = '';
diff --git a/test/core/parser.spec.js b/test/core/parser.spec.js
index b66d9721..b6215052 100644
--- a/test/core/parser.spec.js
+++ b/test/core/parser.spec.js
@@ -1,6 +1,6 @@
 import { describe } from 'node-tdd';
 import { expect } from 'chai';
-import { Ref } from '../../src/core/ref.js';
+import { Ref } from '../../src/core/parser/ref.js';
 import parser from '../../src/core/parser.js';
 import Context from '../../src/core/context.js';
 import generateParsedNeedle from '../helper/generate-parsed-needle.js';
diff --git a/test/core/wildcard.spec.js b/test/core/parser/wildcard.spec.js
similarity index 94%
rename from test/core/wildcard.spec.js
rename to test/core/parser/wildcard.spec.js
index 1d0ff094..ae328bd9 100644
--- a/test/core/wildcard.spec.js
+++ b/test/core/parser/wildcard.spec.js
@@ -1,6 +1,6 @@
 import { expect } from 'chai';
 import { describe } from 'node-tdd';
-import { parseWildcard } from '../../src/core/wildcard.js';
+import { parseWildcard } from '../../../src/core/parser/wildcard.js';
 
 describe('Testing Helper', () => {
   describe('Testing parseWildcard', () => {

From 316ee596df47cf06e3642e80a76df0555b0fb28b Mon Sep 17 00:00:00 2001
From: Lukas Siemon <lukas.siemon@blackflux.com>
Date: Tue, 14 Jun 2022 21:59:52 -0700
Subject: [PATCH 4/4] Revert "chore: refactor"

This reverts commit 9d277a03577e3d6cd24258795587f019e4c29ed3.
---
 src/core/{compiler/iterator.js => compiler-iterator.js} | 2 +-
 src/core/compiler.js                                    | 6 +++---
 src/core/{find/result.js => find-result.js}             | 0
 src/core/find.js                                        | 2 +-
 src/core/{parser/result.js => parser-result.js}         | 4 ++--
 src/core/parser.js                                      | 4 ++--
 src/core/{parser => }/ref.js                            | 0
 src/core/{parser => }/wildcard.js                       | 2 +-
 test/core/parser.spec.js                                | 2 +-
 test/core/{parser => }/wildcard.spec.js                 | 2 +-
 10 files changed, 12 insertions(+), 12 deletions(-)
 rename src/core/{compiler/iterator.js => compiler-iterator.js} (94%)
 rename src/core/{find/result.js => find-result.js} (100%)
 rename src/core/{parser/result.js => parser-result.js} (97%)
 rename src/core/{parser => }/ref.js (100%)
 rename src/core/{parser => }/wildcard.js (97%)
 rename test/core/{parser => }/wildcard.spec.js (94%)

diff --git a/src/core/compiler/iterator.js b/src/core/compiler-iterator.js
similarity index 94%
rename from src/core/compiler/iterator.js
rename to src/core/compiler-iterator.js
index 540cc2e0..b45044e6 100644
--- a/src/core/compiler/iterator.js
+++ b/src/core/compiler-iterator.js
@@ -1,4 +1,4 @@
-import iterator from '../../generic/iterator.js';
+import iterator from '../generic/iterator.js';
 
 export default (tower, needle, tree, { onAdd, onFin }) => {
   const stack = [[[tower, null]]];
diff --git a/src/core/compiler.js b/src/core/compiler.js
index d17cba5b..c36aa9a2 100644
--- a/src/core/compiler.js
+++ b/src/core/compiler.js
@@ -1,9 +1,9 @@
 /* compile needles to hierarchical map object */
 import parser from './parser.js';
-import iterator from './compiler/iterator.js';
+import iterator from './compiler-iterator.js';
 import { defineProperty } from '../generic/helper.js';
-import { Wildcard } from './parser/wildcard.js';
-import { Ref } from './parser/ref.js';
+import { Wildcard } from './wildcard.js';
+import { Ref } from './ref.js';
 
 const LEAF = Symbol('leaf');
 const markLeaf = (input, match, readonly) => defineProperty(input, LEAF, match, readonly);
diff --git a/src/core/find/result.js b/src/core/find-result.js
similarity index 100%
rename from src/core/find/result.js
rename to src/core/find-result.js
diff --git a/src/core/find.js b/src/core/find.js
index fbae9377..6ec59b53 100644
--- a/src/core/find.js
+++ b/src/core/find.js
@@ -3,7 +3,7 @@ import {
   hasMatches, matchedBy, isLastLeafMatch,
   getValues, getOrder, getRoots
 } from './compiler.js';
-import Result from './find/result.js';
+import Result from './find-result.js';
 import { toPath } from '../generic/helper.js';
 
 const formatPath = (input, ctx) => (ctx.joined ? toPath(input) : [...input]);
diff --git a/src/core/parser/result.js b/src/core/parser-result.js
similarity index 97%
rename from src/core/parser/result.js
rename to src/core/parser-result.js
index ea208e7e..2f0ac17d 100644
--- a/src/core/parser/result.js
+++ b/src/core/parser-result.js
@@ -1,5 +1,5 @@
-import assert from '../../generic/assert.js';
-import { defineProperty } from '../../generic/helper.js';
+import assert from '../generic/assert.js';
+import { defineProperty } from '../generic/helper.js';
 import { Wildcard } from './wildcard.js';
 import { Ref } from './ref.js';
 
diff --git a/src/core/parser.js b/src/core/parser.js
index 180e80e2..b52ee4a0 100644
--- a/src/core/parser.js
+++ b/src/core/parser.js
@@ -1,5 +1,5 @@
-import { Wildcard } from './parser/wildcard.js';
-import Result from './parser/result.js';
+import { Wildcard } from './wildcard.js';
+import Result from './parser-result.js';
 
 const throwError = (msg, input, context = {}) => {
   throw new Error(Object.entries(context)
diff --git a/src/core/parser/ref.js b/src/core/ref.js
similarity index 100%
rename from src/core/parser/ref.js
rename to src/core/ref.js
diff --git a/src/core/parser/wildcard.js b/src/core/wildcard.js
similarity index 97%
rename from src/core/parser/wildcard.js
rename to src/core/wildcard.js
index e0f04b41..782127e3 100644
--- a/src/core/parser/wildcard.js
+++ b/src/core/wildcard.js
@@ -1,4 +1,4 @@
-import { escapeRegex, asRegex } from '../../generic/helper.js';
+import { escapeRegex, asRegex } from '../generic/helper.js';
 
 export const parseWildcard = (str) => {
   let regex = '';
diff --git a/test/core/parser.spec.js b/test/core/parser.spec.js
index b6215052..b66d9721 100644
--- a/test/core/parser.spec.js
+++ b/test/core/parser.spec.js
@@ -1,6 +1,6 @@
 import { describe } from 'node-tdd';
 import { expect } from 'chai';
-import { Ref } from '../../src/core/parser/ref.js';
+import { Ref } from '../../src/core/ref.js';
 import parser from '../../src/core/parser.js';
 import Context from '../../src/core/context.js';
 import generateParsedNeedle from '../helper/generate-parsed-needle.js';
diff --git a/test/core/parser/wildcard.spec.js b/test/core/wildcard.spec.js
similarity index 94%
rename from test/core/parser/wildcard.spec.js
rename to test/core/wildcard.spec.js
index ae328bd9..1d0ff094 100644
--- a/test/core/parser/wildcard.spec.js
+++ b/test/core/wildcard.spec.js
@@ -1,6 +1,6 @@
 import { expect } from 'chai';
 import { describe } from 'node-tdd';
-import { parseWildcard } from '../../../src/core/parser/wildcard.js';
+import { parseWildcard } from '../../src/core/wildcard.js';
 
 describe('Testing Helper', () => {
   describe('Testing parseWildcard', () => {