chore(docs): v0.2.20 API docs & examples

Author: FranckFreiburger

docs/api/README.md

@@ -31,7 +31,7 @@
 
 Ƭ  **File**: string \| { content: string ; extname: string  }
 
-*Defined in [index.ts:75](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L75)*
+*Defined in [index.ts:75](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L75)*
 
 Represents the content of the file or the content and the extension name.
 
@@ -41,17 +41,17 @@ Represents the content of the file or the content and the extension name.
 
 • `Const` **version**: string = process.env.VERSION
 
-*Defined in [index.ts:278](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L278)*
+*Defined in [index.ts:287](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L287)*
 
 the version of the library (process.env.VERSION is set by webpack, at compile-time)
 
 ## Functions
 
 ### loadModule
 
-▸ **loadModule**(`path`: string, `options?`: [Options](interfaces/options.md)): Promise<[Module](interfaces/module.md)\>
+▸ **loadModule**(`path`: string, `options?`: [Options](interfaces/options.md)): Promise<any\>
 
-*Defined in [index.ts:750](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L750)*
+*Defined in [index.ts:759](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L759)*
 
 This is the main function.
 
@@ -62,7 +62,7 @@ Name | Type | Default value | Description |
 `path` | string | - | The path of the `.vue` file. If path is not a path (eg. an string ID), your [getFile](interfaces/options.md#getfile) function must return a [File](README.md#file) object. |
 `options` | [Options](interfaces/options.md) | throwNotDefined('options') | The options |
 
-**Returns:** Promise<[Module](interfaces/module.md)\>
+**Returns:** Promise<any\>
 
 A Promise of the component
 

docs/api/interfaces/cache.md

@@ -21,7 +21,7 @@
 
 ▸ **get**(`key`: string): Promise<string\>
 
-*Defined in [index.ts:67](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L67)*
+*Defined in [index.ts:67](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L67)*
 
 #### Parameters:
 
@@ -37,7 +37,7 @@ ___
 
 ▸ **set**(`key`: string, `value`: string): Promise<void\>
 
-*Defined in [index.ts:68](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L68)*
+*Defined in [index.ts:68](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L68)*
 
 #### Parameters:
 

docs/api/interfaces/modulehandler.md

@@ -15,7 +15,7 @@ see [additionalModuleHandlers](options.md#additionalmodulehandlers)
 
 ▸ (`source`: string, `path`: string, `options`: [Options](options.md)): Promise<[Module](module.md)\>
 
-*Defined in [index.ts:261](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L261)*
+*Defined in [index.ts:270](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L270)*
 
 Used by the library when it does not know how to handle a given file type (eg. `.json` files).
 see [additionalModuleHandlers](options.md#additionalmodulehandlers)

docs/api/interfaces/options.md

@@ -30,7 +30,7 @@
 
 • `Optional` **additionalBabelPlugins**: any[]
 
-*Defined in [index.ts:146](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L146)*
+*Defined in [index.ts:153](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L153)*
 
 Additional babel plugins. [TBD]
 
@@ -45,7 +45,7 @@ ___
 
 • `Optional` **additionalModuleHandlers**: Record<string, [ModuleHandler](modulehandler.md)\>
 
-*Defined in [index.ts:153](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L153)*
+*Defined in [index.ts:160](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L160)*
 
 Additional module type handlers. see [ModuleHandler](modulehandler.md)
 
@@ -55,7 +55,7 @@ ___
 
 • `Optional` **compiledCache**: [Cache](cache.md)
 
-*Defined in [index.ts:193](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L193)*
+*Defined in [index.ts:200](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L200)*
 
 [get](cache.md#get)() and [set](cache.md#set)() functions of this object are called when the lib needs to save or load already compiled code. get and set functions must return a `Promise` (or can be `async`).
 Since compilation consume a lot of CPU, is is always a good idea to provide this object.
@@ -99,17 +99,21 @@ ___
 
 • `Optional` **moduleCache**: Record<string, [Module](module.md)\>
 
-*Defined in [index.ts:95](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L95)*
+*Defined in [index.ts:99](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L99)*
 
 Initial cache that will contain resolved dependencies. All new modules go here.
 `vue` must initially be contained in this object.
+[moduleCache](options.md#modulecache) is mandatory for the lib but optional for you. If you do not provide it, the lib will automatically add it to the [[options]] object.
+It is recommended to provide a prototype-less object (`Object.create(null)`) to avoid potential conflict with `Object` properties (constructor, __proto__, hasOwnProperty, ...).
+​ *
+See also [[options.loadModule]].
 
 **example:**
 ```javascript
 	...
-	moduleCache: {
+	moduleCache: Object.assign(Object.create(null), {
 		vue: Vue,
-	},
+	}),
 	...
 ```
 
@@ -119,7 +123,7 @@ Initial cache that will contain resolved dependencies. All new modules go here.
 
 ▸ **addStyle**(`style`: string, `scopeId`: string): void
 
-*Defined in [index.ts:135](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L135)*
+*Defined in [index.ts:142](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L142)*
 
 Called by the library when CSS style must be added in the HTML document.
 
@@ -151,7 +155,7 @@ ___
 
 ▸ **getFile**(`path`: string): Promise<[File](../README.md#file)\>
 
-*Defined in [index.ts:113](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L113)*
+*Defined in [index.ts:120](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L120)*
 
 Called by the library when it needs a file.
 
@@ -168,9 +172,12 @@ a Promise of the file content (UTF-8)
 **example:**
 ```javascript
 	...
-	getFile(url) {
+	async getFile(url) {
 
-		return fetch(url).then(response => response.ok ? response.text() : Promise.reject(response));
+		const res = await fetch(url);
+		if ( !res.ok )
+			throw Object.assign(new Error(url+' '+res.statusText), { res });
+		return await res.text();
 	},
 	...
 ```
@@ -181,7 +188,7 @@ ___
 
 ▸ `Optional`**loadModule**(`path`: string, `options`: [Options](options.md)): Promise<[Module](module.md) \| undefined\>
 
-*Defined in [index.ts:230](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L230)*
+*Defined in [index.ts:239](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L239)*
 
 Called when the lib requires a module. Do return `undefined` to let the library handle this.
 
@@ -196,6 +203,8 @@ Name | Type | Description |
 
 A Promise of the module or undefined
 
+[moduleCache](options.md#modulecache) and [Options.loadModule](options.md#loadmodule) are strongly related, in the sense that the result of [[options.loadModule]] is stored in [moduleCache](options.md#modulecache).
+However, [[options.loadModule]] is asynchronous and may help you to handle modules or components that are conditionally required (optional features, current languages, plugins, ...).
 ```javascript
 	...
 	loadModule(path, options) {
@@ -212,7 +221,7 @@ ___
 
 ▸ `Optional`**log**(`type`: string, ...`data`: any[]): void
 
-*Defined in [index.ts:211](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/547328e/src/index.ts#L211)*
+*Defined in [index.ts:218](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/c0792ec/src/index.ts#L218)*
 
 Called by the library when there is somthing to log (eg. scripts compilation errors, template compilation errors, template compilation  tips, style compilation errors, ...)