feat: support recursive types (#9)

BREAKING CHANGE: `ExampleGenerator` now requires as input a tuple `[number,FuzzContext]`

BREAKING CHANGE: concrete fuzzer functions are passed as their first argument a FuzzContext specifying whether to recurse further or not

BREAKING CHANGE: deprecated, non-configurable versions of core fuzzers removed

Author: holvonixAdvay

.gitignore

@@ -1,3 +1,4 @@
+.vscode
 .DS_Store
 *.DS_Store
 

README.md

@@ -21,12 +21,12 @@ const target = t.union([t.string, t.type({n:t.number, b:t.boolean})]);
 // Builds a particular fuzzer from the registry.
 const fuzzer = fuzz.exampleGenerator(r, target);
 
-// Make examples. The input number fully determines
-// the output example.
-console.log(fuzzer.encode(0));
-console.log(fuzzer.encode(1));
-console.log(fuzzer.encode(2));
-console.log(fuzzer.encode(493));
+// Make examples. The input integer and context
+// fully determines the output example.
+console.log(fuzzer.encode([0, fuzz.fuzzContext()]));
+console.log(fuzzer.encode([1, fuzz.fuzzContext()]));
+console.log(fuzzer.encode([2, fuzz.fuzzContext()]));
+console.log(fuzzer.encode([493, fuzz.fuzzContext()]));
 ````
 
 ## Types Supported
@@ -45,6 +45,7 @@ Currently supports (and their nested closure):
 * `t.partial`
 * `t.readonly`
 * `t.readonlyArray`
+* `t.recursive`
 * `t.string`
 * `t.tuple`
 * `t.type` (interface)
@@ -59,7 +60,7 @@ Currently supports (and their nested closure):
 ### Generating Conforming Examples and Verifying Decoder Behavior
 
 Given a `d = t.Decoder<I,A>` (aka a `t.Type`), `fuzz.exampleGenerator` will
-build a `t.Encoder<number,A>` that will give example instances of `A`.
+build a `t.Encoder<[number,FuzzContext],A>` that will give example instances of `A`.
 The example instances should all pass on `d.decode`, which should return
 an identical example.  No exceptions should be thrown.
 
@@ -72,6 +73,20 @@ fuzzers, currently:
 * extra properties inserted into `partial` and `type` (interface) objects
 * type used to fuzz `unknown` types
 
+### Recursive Types
+
+When fuzzing recursive types, you can provide to the context
+a `maxRecursionHint` which specifies the requested maximum
+instantiations of any recursive type.  Note that this is the
+maximum depth of *recursive* types, not all types.  If the
+recursive depth has been reached, fuzzers that have a choice
+of which child(ren) to instantiate (like unions, partials,
+or arrays) will attempt to choose children that won't recurse.
+
+Note this is only a hint -- sometimes the type definition won't allow the fuzzer to choose such a non-recursive path
+(and you'll get a stack limit error when attempting to
+generate the actual example from the generator).
+
 ### Fuzzing a Type (TODO)
 
 

package.json

@@ -99,13 +99,17 @@
     "spec": "./build/test/**/test-*.js"
   },
   "dependencies": {
+    "fp-ts": "^2.0.3",
     "io-ts": "^2.0.0",
-    "fp-ts": "^2.0.3"
+    "seedrandom": "^3.0.1"
   },
   "devDependencies": {
     "@holvonix-open/release-config-js": "^1.0.3",
+    "@types/chai": "^4.1.7",
     "@types/mocha": "^5.2.5",
     "@types/node": "^12.6.9",
+    "@types/seedrandom": "^2.4.28",
+    "chai": "^4.2.0",
     "chokidar-cli": "^2.0.0",
     "codecov": "^3.4.0",
     "concurrently": "^4.1.1",