[Docs] Update documentation

docs/docs/Getting-Started/installation.md

@@ -1,3 +1,14 @@
+## Requirements
+
+This project is built on top of base Node.js with TypeScript and is meant primarily for Node-based applications with
+possible usage at static client-side applications with embedded JavaScript code.
+
+To remain as lightweight as possible, to use the base framework you only need to have virtually any JavaScript runtime
+environment - no matter if it's a Node.js or a page in your browser.
+
+If you choose to use any of the Falbricate Plugins, there might be some further requirements.
+
+
 # Installation
 
 To install the base for this library, you only need to enter the following
@@ -10,6 +21,7 @@ npm install @falbricate/base
 This gives you the base frame with basic functionality you can use to generate
 your falsa objects.
 
+
 ## Plugins
 
 Currently, there are no plugins available yet, but I'm working on it!

docs/docs/System-Documentation/00_introduction.md

@@ -2,35 +2,42 @@
 
 The whole ecosystem is based on various building blocks. This section aims on giving an introduction into them.
 
+
 ## Fabrication Pipeline
 
-Fabrication Pipeline represents the whole flow of the falsa generation.
+Fabrication Pipeline represents the whole flow of the falsa generation - from loading and compiling of a given
+schema to generation of falsum objects.
+
 
 ## Fabricator
 
 Fabricator is a base entrypoint to the whole fabrication ecosystem. This component is responsible for managing and
 maintaining of the whole falsa generation - _fabrication pipeline_.
 
+
 ## Schema
 
 Schema is an internal representation of what the client described in his [Schema Input](#schema-input) provided
 to [Fabricator](#fabricator) and what is he expected to have at the end of the fabrication pipeline.
 
+
 ## Schema Input
 
 Schema Input represents client given declaration of how should the generated falsa look like.
 
 This input is then compiled inside in the Fabricator into the actual Schema that is being used in the
 Fabrication Pipeline.
 
+
 ## Value Generator
 
-Value generator is a in-depth component being able to generate a specific type of value. There are many kinds of them
+Value generator is a component being able to generate a specific type of values. There are many kinds of them
 defined in the ecosystem; each using a different strategy and providing a different kind of value generation.
 
-Each Value Generator has its name assigned, so you can always refer to it by the name. You can also generate your own
-generators when you find yourself in situation of not finding any suitable solution; and you can also register it to
-access it as you need:
+Each Value Generator has its name assigned, so you can always refer to it by its name. You can also generate your own
+generators when you find yourself in situation of not finding any suitable solution. You can also register them to
+access your specifics whenever you need:
+
 
 ```typescript linenums="1"
 import { registerValueGenerator, get } from '@falbricate/base';
@@ -42,7 +49,7 @@ registerValueGenerator(
 );
 
 // Accessing your Value Generator in code
-const generator = get('my-custom-generator', {
+const generator = getValueGenerator('my-custom-generator', {
   requiredParam1: 'my-parameter',
   requiredParam2: 123,
 });

docs/docs/System-Documentation/Building-Blocks/01_schema.md

@@ -10,13 +10,19 @@ which is provided by the client.
 
 Schema (as an instance of `Schema` class) consists of:
 
-- Fields Definition - which fields should be generated, what resources should be used to provide a value,
-  what values should be generated for them and how these should be modified. It not only uses
+- Fields Definition - which fields should be generated, what resources has to be used to provide values,
+  what values shall be generated for them and how these values expected to be modified. It not only uses
   [Value Generators](./03_value-generator.md) for retrieving a value for the field name, it also pipes the value
   through [Value Pipes](../Pipes/Value-Pipes/00_value-pipes.md)
 
 - Falsum Pipes - pipes modifying the generated object by this schema ([more on Falsum Pipes](../Pipes/Falsum-Pipes/00_falsum-pipes.md))
 
+- Profiles - pregenerated values (uniquely for each falsum generation) being accessible from the value generators 
+  to maintain the result Falsum within a given context. For example when you generate an object representing a 
+  person born in Germany, the city of birth mustn't be Paris, his nationality will most likely remain german and 
+  his name will probably be Hans. See more on [Profiles](../Profiles/00_introduction.md).
+
+
 ## How is the Schema used
 
 Schema is a root for `Fabricator` which uses it for Falsum fabrication. More on [Fabricator](./04_fabricator.md)

docs/docs/System-Documentation/Building-Blocks/02_schema-input.md

@@ -7,6 +7,7 @@ the fabricated falsum look like.
 Similarly to [Schema](./01_schema.md), the Schema Input also contains declarations of fields with
 [Value Generators](./03_value-generator.md) assigned.
 
+
 ## Schema Declaration
 
 The whole process of describing the schema via Schema Input was designed with a high emphasis

docs/docs/System-Documentation/Building-Blocks/03_value-generator.md

@@ -1,6 +1,6 @@
 # Value Generator
 
-Value Generator provides a service to generate a value the Falsum consists of. These generators are designed to be
+Value Generator provides a service to generate values the Falsum consists of. These generators are designed to be
 able to generate a random (or for example to simply pass predefined value from context) and return it. This service is
 used for generating a falsum by given schema.
 
@@ -10,18 +10,19 @@ Then, the generator on its `get(context: GenerationContext)` method call returns
 
 For example how can you use the generator, have a look on [how to access the generator](#accessing-value-generators).
 
+
 ## Accessing Value Generators
 
 Value generators are basically classes (or instances if you wish). It can be accessed as any other
 class instance you know.
 
 !!! example
 
-    Accessing to the generator as to a class instance
+    Accessing the generator as a class instance
 
     ``` typescript
     const generator = new IntegerGenerator({ max: 17 });
-    const value = generator.get();
+    const value = generator.generate();
     ```
 
 But this is not the only way you can use these generators. The Falbricate ecosystem also enables you to
@@ -73,7 +74,7 @@ your own Value Generators!
 To create a Value Generator and to use it within the ecosystem, you need to follow simple rules:
 
 1. The generator needs to extend an abstract and generic class `ValueGenerator<ValueType, Configuration>`
-2. Yours configuration must be a superset of the `ValueGeneratorConfig` type
+2. Your configuration must be a superset of the `ValueGeneratorConfig` type
 3. _(Optional) if you want to register your value generator, you must follow [these instructions](#register-custom-value-generator)_
 
 !!! example

docs/docs/System-Documentation/Building-Blocks/05_context.md

@@ -9,17 +9,17 @@ Partially it's given by client, partially it's a context provided internally by
 ## Contents of the Context
 
 Context consists of multiple parts. First and the most important is the context the
-client provides. The client can put as the context whatever he needs.
+client provides. The client can put as the context whatever he might need for generation.
 
 For example have a look at [Context Accessor](../Generators/07_contextuals.md#context-accessor).
 
 But there are also items added to the context internally:
 
-- `index` - number of generated item in the row (counting from 0). More important
-  when using `Fabricator#generateMany(n, context)` method
+- `index` - number of currently generated item in a row (counting from 0); more useful
+  when invoking `Fabricator#generateMany(n, context)` method
 
 - `current` - falsum being currently fabricated; useful when you need to access
-  other properties to stay consistent within falsa
+  other properties to stay consistent within falsum
 
 - `previous` - previously fabricated falsum; only populated when using
   `Fabricator#generateMany(n, context)` method
@@ -30,8 +30,8 @@ But there are also items added to the context internally:
     are being merged giving the clinet the opportunity to alter the context as he wish
     and whenever he needs.
 
-    **On the other hand, be careful when doing so - you can simply get into unexpected
-    behaviour just by overriding some of these default context proeprties!**
+    **On the other hand, be careful when doing so - you can easily get into unexpected
+    behaviour just by overriding some of these default context properties!**
 
 !!! example "Example Context"
 

docs/docs/System-Documentation/Generators/02_strings.md

@@ -2,6 +2,12 @@
 
 Here is a list of predefined generators for generating string values.
 
+
+!!! note
+
+    These generators are well combined with [Charsets](../../Utils/charset.md) feature  
+
+
 ## Random String of lenght
 
 Generates a random string based on desired `length` (number) and given `charset`.

docs/docs/System-Documentation/Generators/04_dates.md

@@ -4,7 +4,7 @@ Here are listed predefined date generators.
 
 ## Date in range
 
-This generator generates dates withing the specified range.
+This generator generates dates within a specified range.
 
 ### Configuration
 

docs/docs/System-Documentation/Generators/05_arrays.md

@@ -81,7 +81,7 @@ a shuffled sample of it.
 It takes `array` field as a non-empty array of items of any type and
 the `sampleSize` which is any integer number greater than 0.
 
-When these requirements are not met, it throws an error; so does when the
+When these requirements are not met, it throws an error; so it does when the
 sample size is greater than the length of the given array.
 
 ### Examples

docs/docs/System-Documentation/Generators/06_objects.md

@@ -105,7 +105,7 @@ schema object will be used to generate nested falsum.
 
 ## List of Objects from Schema
 
-Builds up a list of an objects by given schema.
+Builds up a list of objects by given schema.
 
 The configuration object is required to have `schema` field containing
 a [Schema Input](../Building-Blocks/02_schema-input.md) object. This configured

docs/docs/System-Documentation/Generators/07_contextuals.md

@@ -6,7 +6,7 @@ Here is a list of predefined generators retrieving values from
 ## Context Accessor
 
 Returns a value from the received context. The value is reached by the given
-path the value shall be at.
+path the value is expected to be at.
 
 === "Configuration Declaration"
 
@@ -38,12 +38,12 @@ path the value shall be at.
     };
     ```
 
-- `path` represents the path in the given fabrication context (like `data.myContext.myValue`)
+- `path` represents the path in the given fabrication context (like `profiles.identifiers.uuid`)
 
 - `sep` represents separator to be used on path; by default it's a dot (`.`); supported
   values are `.`, `/`, `#` and `$`
 
-- `handleError` tells the accessor that if there is no value on the path or it comes into another
+- `handleError` tells the accessor that if there is no value on the path or when it comes into another
   issue, if it should try to handle or should fail in the first place. By default, it lets the error
   to be thrown. Otherwise, it uses _null-like_ value specified in `useErrorValue`
 

docs/docs/System-Documentation/Generators/09_ip_addresses.md

@@ -6,14 +6,14 @@ This generator is responsible for generating random IP Address (v4) in a given r
 
 !!! example
 
-```typescript linenums="1"
-const config: IPAddressConfig = {
-  octet1: { min: 10, max: 12 },
-  octet2: { min: 1, max: 32 },
-  octet3: { min: 1, max: 254 },
-  octet4: { min: 1, max: 254 },
-};
-```
+    ```typescript linenums="1"
+    const config: IPAddressConfig = {
+      octet1: { min: 10, max: 12 },
+      octet2: { min: 1, max: 32 },
+      octet3: { min: 1, max: 254 },
+      octet4: { min: 1, max: 254 },
+    };
+    ```
 
 ## Examples
 

docs/docs/System-Documentation/Nullability/00_nullability.md

@@ -1,7 +1,7 @@
 # Nullability Configuration
 
-Nullability is a feature for enabling to specify to the Value Generator to include _null-like_ values instead
-of the specified ones - on demand. Sometimes it's useful.
+Nullability is a feature for enabling the client to specify to the Value Generator to include 
+_null-like_ values instead of the specified ones - on demand. 
 
 ## Configuration
 
@@ -23,9 +23,9 @@ be `null` or `undefined`.
 
 This is an example how you can implement the nullability into your Schemas.
 
-=== "Using with Value Generator"
+!!! example "Using with Value Generator"
 
-    ``` typescript linenums="1"
+    ```typescript linenums="1"
     const config: ConstantValueConfig = {
         value: "my constant value",
         nullability: {

docs/docs/System-Documentation/Pipes/Falsum-Pipes/00_falsum-pipes.md

@@ -202,9 +202,9 @@ to register it into internal registry of Falsum Pipes.
     with such name registered, it will throw an Error when trying to store!
 
 !!! tip "Naming conventions"
-It doesn't matter what name do you use. As long as it's a string. But
-it's a best practice to avoid using whitespaces or special characters.
-Shouldn't stop working if you do, though...
+    It doesn't matter what name do you use. As long as it's a string. But
+    it's a best practice to avoid using whitespaces or special characters.
+    Shouldn't stop working if you do, though...
 
 Now, when you have your custom pipe registered, you can use it in your schema
 by just referring to it by previously given name:

docs/docs/System-Documentation/Pipes/Value-Pipes/00_value-pipes.md

@@ -58,7 +58,7 @@ returned as the result of the Value Generator.
 
     ``` typescript linenums="1"
     const config: ConstantValueConfig = {
-        value: 'my constant string',
+        value: 'my testing value',
         pipes: [
             'uppercase'
         ]

docs/docs/System-Documentation/Profiles/00_introduction.md

@@ -7,9 +7,15 @@ These prepared data objects are meant to be accessible through a context object
 provided to each Falsum Fabrication run. So, you can easily access them
 using context accessors without needing to declare these on your own.
 
+These are also meant to share pre-generated values for the falsum to remain
+internally consistent; _e.g._ person born in Germany will probably have german
+nationality, probably will have a telephone number starting with `+49` local prefix,
+main language will be german and first name will most likely be Hans.
+
+
 ## Schema Declaration
 
-To declare you want to have access to a profile, you need to provide
+To declare that you want to have access to a profile, you need to provide
 the profile's name into a [Schema input](../Building-Blocks/02_schema-input.md)
 like this:
 

docs/docs/System-Documentation/Standards/00_introduction.md

@@ -6,23 +6,24 @@ Value Generators do not require any further configuration, their specification i
 To describe to the [Fabricator](../Building-Blocks/04_fabricator.md) you want to use a specific standard value
 generator in your schema, you only need to attach the standard's name to the field.
 
+
 !!! example
 
-````typescript linenums="1"
-const schema: SchemaInput = {
-fields: {
-myStandardField: 'some-standard-name',
-myAnotherStandardField: 'some-another-standard-name',
-onceMoreStandardField: 'some-different-standard-name',
+    ```typescript linenums="1"
+    const schema: SchemaInput = {
+        fields: {
+            myStandardField: 'some-standard-name',
+            myAnotherStandardField: 'some-another-standard-name',
+            onceMoreStandardField: 'some-different-standard-name',
 
-          // ... Some other desired fields ...
-      },
+            // ... Some other desired fields ...
+        },
 
-      // ... Other configuration when desired ...
+        // ... Other configuration when desired ...
     };
-
+    
     const fabricator = new Fabricator(config);
-
+    
     console.log(fabricator.generate());
     ```
 
@@ -82,12 +83,12 @@ function. This is basically a function defined like this:
 
 ```typescript
 export type StandardValueGeneratorBuilder = () => StandardValueGenerator;
-````
+```
 
 This means the builder function is just returning your Standard Value Generator on demand (on invocation). To
 actually perform the registration, pick a unique name and store it like this:
 
-```typescript linenums="1"
+```typescript
 registerStandard('hello-world-standard', () => new HelloWorldStandard());
 ```