als-require/docs/03-usage.md

A utility for using CommonJS require in the browser and creating bundles.

## Usage

`als-require` has two files for NodeJS and browser which has same structure and api. 

### Constructor
Constructor initiating new Require instance. 
On Nodejs, it's automaticly reading all modules and applying plugins. 
In browser, you should run async method `getContent` for reading modules and applying plugins.

Constructor has two parameters: path and options. 
The path is a string relative path to modules. And options has `plugins`, `logger` and flag for allowing `cyclicDependencies`.

```js
const plugins = [
   function(mod) {
      const {content,children,path} = mod
      mod.content = content.replace(...)
   }
]
const options = { plugins = [], cyclicDependencies = false, logger = console }
```

### fn and stringFn parameters

The `fn` method generates an executable function containing the bundled modules. 
This function accepts custom parameters and includes pre- and post-bundle code if specified.

The `stringFn` method behaves similarly but returns the generated function as a string.
This is particularly useful for embedding the function in HTML or scripts.


Here are parameters:
* `scriptBefore` - Should be script as string to run it before bundle
* `scriptAfter` - Should be script as string to run it after bundle
  * In this stage available two variables: `modules` and `result`.
    * `modules` - the object which includes all modules ({path:content,...})
    * `result` - the function to run bundle which returned after `scriptAfter`
  * In this stage, you can add return for returning something else
* `parameters` - The array of strings which will include parameters to pass in result's fn
* `name` - Only for `stringFn` for changing function name
  * For example, for icluding it in html and call by it's name


### Node.Js

```js
// Import the Require class
const Require = require('als-require');

// Create a new Require instance with options
const mod = new Require('./relative/path/to/module', {
   plugins: [],
   cyclicDependencies: true,
   logger: console
});

// Define custom parameters and scripts
const parameters = ['name'];
const scriptBefore = "const SomeVariableAvailableForAllModules = `Hello ${name}`;";
const scriptAfter = `
   console.log('All modules processed.');
   return result;
`;

// Generate the executable function
const resultFn = mod.fn({ scriptBefore, scriptAfter, parameters });

// Generate the function as a string with a custom name
const name = 'bundleFn';
const bundleString = mod.stringFn({ scriptBefore, scriptAfter, parameters, name });

// Execute the result function
const result = resultFn('Alex');
console.log(result);

// Example: Embed the bundle string in a script
const bundle = `${bundleString}\n const result = ${name}('Alex');`;
console.log(bundle);
```



### Browser

```html
<script src="/node_modules/als-require/require.js"></script>
<script>
   const scriptBefore = "const globalVar = 'Hello, world!';";
   const scriptAfter = "console.log('Bundle execution complete.');";
   const parameters = ['customParam'];

   // Create a Require instance for the browser
   const mod = new Require('./relative/path/to/module');

   // Fetch and load all module dependencies
   mod.getContent().then((mod) => {
      // Define parameters and custom scripts

      // Generate the executable function
      const resultFn = mod.fn({ scriptBefore, scriptAfter, parameters });

      // Execute the generated function
      const result = resultFn('Value');
      console.log(result);
   });

   // or
   require('./relative/path/to/module',{ scriptBefore, scriptAfter, parameters },'Value')
   .then(result => console.log(result))

</script>

```