Skip to content

Commit

Permalink
chore(docs): v0.8.0 API docs & examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@FranckFreiburger
FranckFreiburger committed May 31, 2021
1 parent 04817e0 commit 0e57e5c
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 61 deletions.
74 changes: 42 additions & 32 deletions docs/api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@

* [AbstractPath](README.md#abstractpath)
* [Cache](README.md#cache)
* [ContentData](README.md#contentdata)
* [CustomBlock](README.md#customblock)
* [CustomBlockCallback](README.md#customblockcallback)
* [File](README.md#file)
Expand Down Expand Up @@ -44,7 +45,7 @@

Ƭ **AbstractPath**: { toString: () => string }

*Defined in [types.ts:24](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L24)*
*Defined in [types.ts:29](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L29)*

#### Type declaration:

Expand All @@ -58,7 +59,7 @@ ___

Ƭ **Cache**: { get: (key: string) => Promise<string\> ; set: (key: string, value: string) => Promise<void\> }

*Defined in [types.ts:15](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L15)*
*Defined in [types.ts:20](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L20)*

#### Type declaration:

Expand All @@ -69,11 +70,19 @@ Name | Type |

___

### ContentData

Ƭ **ContentData**: string \| ArrayBuffer

*Defined in [types.ts:71](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L71)*

___

### CustomBlock

Ƭ **CustomBlock**: { attrs: Record<string, string \| true\> ; content: string ; type: string }

*Defined in [types.ts:101](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L101)*
*Defined in [types.ts:109](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L109)*

A custom block

Expand All @@ -91,25 +100,25 @@ ___

Ƭ **CustomBlockCallback**: (component: [ModuleExport](README.md#moduleexport)) => void

*Defined in [types.ts:95](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L95)*
*Defined in [types.ts:103](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L103)*

CustomBlockCallback function type

___

### File

Ƭ **File**: { content: string \| ArrayBuffer ; type: string }
Ƭ **File**: { getContentData: (asBinary: Boolean) => Promise<[ContentData](README.md#contentdata)\> ; type: string }

*Defined in [types.ts:69](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L69)*
*Defined in [types.ts:77](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L77)*

Represents a file content and the extension name.

#### Type declaration:

Name | Type | Description |
------ | ------ | ------ |
`content` | string \| ArrayBuffer | The content data |
`getContentData` | (asBinary: Boolean) => Promise<[ContentData](README.md#contentdata)\> | The content data accessor (request data as text of binary) |
`type` | string | The content type (file extension name, eg. '.svg' ) |

___
Expand All @@ -118,15 +127,15 @@ ___

Ƭ **LangProcessor**: (source: string, preprocessOptions?: any) => Promise<string\> \| string

*Defined in [types.ts:374](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L374)*
*Defined in [types.ts:399](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L399)*

___

### Module

Ƭ **Module**: { exports: [ModuleExport](README.md#moduleexport) }

*Defined in [types.ts:121](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L121)*
*Defined in [types.ts:129](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L129)*

This just represents a loaded js module

Expand All @@ -142,25 +151,25 @@ ___

Ƭ **ModuleCacheId**: string

*Defined in [types.ts:21](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L21)*
*Defined in [types.ts:26](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L26)*

___

### ModuleExport

Ƭ **ModuleExport**: {}

*Defined in [types.ts:115](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L115)*
*Defined in [types.ts:123](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L123)*

This just represents a loaded js module exports

___

### ModuleHandler

Ƭ **ModuleHandler**: (type: string, source: string, path: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[ModuleExport](README.md#moduleexport) \| null\>
Ƭ **ModuleHandler**: (type: string, getContentData: File[\"getContentData\"], path: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[ModuleExport](README.md#moduleexport) \| null\>

*Defined in [types.ts:63](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L63)*
*Defined in [types.ts:68](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L68)*

Used by the library when it does not know how to handle a given file type (eg. `.json` files).
see [[moduleHandlers]]
Expand All @@ -185,23 +194,24 @@ ___

### Options

Ƭ **Options**: { additionalBabelPlugins?: Record<string, any\> ; compiledCache?: [Cache](README.md#cache) ; delimiters?: [string, string] ; handleModule?: [ModuleHandler](README.md#modulehandler) ; moduleCache?: Record<[ModuleCacheId](README.md#modulecacheid), LoadingType<[ModuleExport](README.md#moduleexport)\> \| [ModuleExport](README.md#moduleexport)\> ; pathResolve: [PathResolve](README.md#pathresolve) ; addStyle: (style: string, scopeId: string \| undefined) => void ; customBlockHandler?: (block: [CustomBlock](README.md#customblock), filename: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[CustomBlockCallback](README.md#customblockcallback) \| undefined\> ; getFile: (path: [AbstractPath](README.md#abstractpath)) => Promise<[File](README.md#file)\> ; getResource: (pathCx: [PathContext](README.md#pathcontext), options: [Options](README.md#options)) => [Resource](README.md#resource) ; loadModule?: (path: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[ModuleExport](README.md#moduleexport) \| undefined\> ; log?: (type: string, ...data: any[]) => void }
Ƭ **Options**: { additionalBabelParserPlugins?: babel\_ParserPlugin[] ; additionalBabelPlugins?: Record<string, any\> ; compiledCache?: [Cache](README.md#cache) ; delimiters?: [string, string] ; handleModule?: [ModuleHandler](README.md#modulehandler) ; moduleCache: Record<[ModuleCacheId](README.md#modulecacheid), LoadingType<[ModuleExport](README.md#moduleexport)\> \| [ModuleExport](README.md#moduleexport)\> ; pathResolve: [PathResolve](README.md#pathresolve) ; addStyle: (style: string, scopeId: string \| undefined) => void ; customBlockHandler?: (block: [CustomBlock](README.md#customblock), filename: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[CustomBlockCallback](README.md#customblockcallback) \| undefined\> ; getFile: (path: [AbstractPath](README.md#abstractpath)) => Promise<[File](README.md#file) \| [ContentData](README.md#contentdata)\> ; getResource: (pathCx: [PathContext](README.md#pathcontext), options: [Options](README.md#options)) => [Resource](README.md#resource) ; loadModule?: (path: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[ModuleExport](README.md#moduleexport) \| undefined\> ; log?: (type: string, ...data: any[]) => void }

*Defined in [types.ts:132](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L132)*
*Defined in [types.ts:140](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L140)*

#### Type declaration:

Name | Type | Description |
------ | ------ | ------ |
`additionalBabelParserPlugins?` | babel\_ParserPlugin[] | Additional babel parser plugins. [TBD] ```javascript ... ... ``` |
`additionalBabelPlugins?` | Record<string, any\> | Additional babel plugins. [TBD] ```javascript ... ... ``` |
`compiledCache?` | [Cache](README.md#cache) | [get](README.md#get)() and [set](README.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. **example:** In the following example, we cache the compiled code in the browser's local storage. Note that local storage is a limited place (usually 5MB). Here we handle space limitation in a very basic way. Maybe (not tested), the following libraries may help you to gain more space [pako](https://github.com/nodeca/pako), [lz-string](https://github.com/pieroxy/lz-string/) ```javascript ... compiledCache: { set(key, str) { // naive storage space management for (;;) { try { // doc: https://developer.mozilla.org/en-US/docs/Web/API/Storage window.localStorage.setItem(key, str); break; } catch(ex) { // here we handle DOMException: Failed to execute 'setItem' on 'Storage': Setting the value of 'XXX' exceeded the quota window.localStorage.removeItem(window.localStorage.key(0)); } } }, get(key) { return window.localStorage.getItem(key); }, }, ... ``` |
`delimiters?` | [string, string] | Sets the delimiters used for text interpolation within the template. Typically this is used to avoid conflicting with server-side frameworks that also use mustache syntax. ```javascript ... <script> // <!-- const vueContent = ` <template> Hello [[[[ who ]]]] !</template> <script> export default { data() { return { who: 'world' } } } </script> `; // --> const options = { moduleCache: { vue: Vue }, getFile: () => vueContent, addStyle: () => {}, delimiters: ['[[[[', ']]]]'], } const app = Vue.createApp(Vue.defineAsyncComponent(() => window['vue3-sfc-loader'].loadModule('file.vue', options))); app.mount(document.body); </script> ... ``` |
`handleModule?` | [ModuleHandler](README.md#modulehandler) | Handle additional module types (eg. '.svg', '.json' ). see [ModuleHandler](README.md#modulehandler) |
`moduleCache?` | Record<[ModuleCacheId](README.md#modulecacheid), LoadingType<[ModuleExport](README.md#moduleexport)\> \| [ModuleExport](README.md#moduleexport)\> | Initial cache that will contain resolved dependencies. All new modules go here. `vue` must initially be contained in this object. [moduleCache](README.md#modulecache) is mandatory for the lib. If you do not provide it, the library will create one. 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: Object.assign(Object.create(null), { vue: Vue, }), ... ``` |
`moduleCache` | Record<[ModuleCacheId](README.md#modulecacheid), LoadingType<[ModuleExport](README.md#moduleexport)\> \| [ModuleExport](README.md#moduleexport)\> | Initial cache that will contain resolved dependencies. All new modules go here. `vue` must initially be contained in this object. [moduleCache](README.md#modulecache) is mandatory and should be shared between options objects used for you application (note that you can also pass the same options object through multiple loadModule calls) 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: Object.assign(Object.create(null), { vue: Vue, }), ... ``` |
`pathResolve` | [PathResolve](README.md#pathresolve) | Abstact path handling |
`addStyle` | (style: string, scopeId: string \| undefined) => void | - |
`customBlockHandler?` | (block: [CustomBlock](README.md#customblock), filename: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[CustomBlockCallback](README.md#customblockcallback) \| undefined\> | - |
`getFile` | (path: [AbstractPath](README.md#abstractpath)) => Promise<[File](README.md#file)\> | - |
`getFile` | (path: [AbstractPath](README.md#abstractpath)) => Promise<[File](README.md#file) \| [ContentData](README.md#contentdata)\> | - |
`getResource` | (pathCx: [PathContext](README.md#pathcontext), options: [Options](README.md#options)) => [Resource](README.md#resource) | - |
`loadModule?` | (path: [AbstractPath](README.md#abstractpath), options: [Options](README.md#options)) => Promise<[ModuleExport](README.md#moduleexport) \| undefined\> | - |
`log?` | (type: string, ...data: any[]) => void | - |
Expand All @@ -212,7 +222,7 @@ ___

Ƭ **PathContext**: { refPath: [AbstractPath](README.md#abstractpath) ; relPath: [AbstractPath](README.md#abstractpath) }

*Defined in [types.ts:33](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L33)*
*Defined in [types.ts:38](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L38)*

A PathContext represents a path (relPath) relative to an abolute path (refPath)
Note that relPath is not necessary relative, but it is, relPath is relative to refPath.
Expand All @@ -230,7 +240,7 @@ ___

Ƭ **PathResolve**: (pathCx: [PathContext](README.md#pathcontext)) => [AbstractPath](README.md#abstractpath)

*Defined in [types.ts:42](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L42)*
*Defined in [types.ts:47](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L47)*

relative to absolute module path resolution

Expand All @@ -240,7 +250,7 @@ ___

Ƭ **Resource**: { getContent: () => Promise<[File](README.md#file)\> ; id: [ModuleCacheId](README.md#modulecacheid) ; path: [AbstractPath](README.md#abstractpath) }

*Defined in [types.ts:80](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/types.ts#L80)*
*Defined in [types.ts:88](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/types.ts#L88)*

Represents a resource.

Expand All @@ -258,9 +268,9 @@ Name | Type | Description |

• `Const` **version**: string = process.env.VERSION

*Defined in [tools.ts:53](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/tools.ts#L53)*
*Defined in [tools.ts:53](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/tools.ts#L53)*

*Defined in [index.ts:24](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/index.ts#L24)*
*Defined in [index.ts:26](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/index.ts#L26)*

the version of the library (process.env.VERSION is set by webpack, at compile-time)

Expand All @@ -270,15 +280,15 @@ ___

• `Const` **vueVersion**: string

*Defined in [createSFCModule.ts:4](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/createSFCModule.ts#L4)*
*Defined in [createSFCModule.ts:4](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/createSFCModule.ts#L4)*

## Functions

### buildTemplateProcessor

▸ **buildTemplateProcessor**(`processor`: [LangProcessor](README.md#langprocessor)): object

*Defined in [index.ts:157](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/index.ts#L157)*
*Defined in [index.ts:179](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/index.ts#L179)*

Convert a function to template processor interface (consolidate)

Expand All @@ -300,7 +310,7 @@ ___

▸ **createSFCModule**(`source`: string, `filename`: [AbstractPath](README.md#abstractpath), `options`: [Options](README.md#options)): Promise<[ModuleExport](README.md#moduleexport)\>

*Defined in [createSFCModule.ts:3](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/createSFCModule.ts#L3)*
*Defined in [createSFCModule.ts:3](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/createSFCModule.ts#L3)*

#### Parameters:

Expand All @@ -318,7 +328,7 @@ ___

▸ **defaultGetResource**(`pathCx`: [PathContext](README.md#pathcontext), `options`: [Options](README.md#options)): [Resource](README.md#resource)

*Defined in [index.ts:73](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/index.ts#L73)*
*Defined in [index.ts:76](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/index.ts#L76)*

Default getResource implementation
by default, getContent() use the file extension as file type.
Expand All @@ -336,9 +346,9 @@ ___

### defaultHandleModule

▸ **defaultHandleModule**(`type`: string, `source`: string, `path`: [AbstractPath](README.md#abstractpath), `options`: [Options](README.md#options)): Promise<[ModuleExport](README.md#moduleexport) \| null\>
▸ **defaultHandleModule**(`type`: string, `getContentData`: File[\"getContentData\"], `path`: [AbstractPath](README.md#abstractpath), `options`: [Options](README.md#options)): Promise<[ModuleExport](README.md#moduleexport) \| null\>

*Defined in [tools.ts:377](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/tools.ts#L377)*
*Defined in [tools.ts:372](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/tools.ts#L372)*

Default implementation of handleModule

Expand All @@ -347,7 +357,7 @@ Default implementation of handleModule
Name | Type |
------ | ------ |
`type` | string |
`source` | string |
`getContentData` | File[\"getContentData\"] |
`path` | [AbstractPath](README.md#abstractpath) |
`options` | [Options](README.md#options) |

Expand All @@ -359,7 +369,7 @@ ___

▸ `Const`**defaultPathResolve**(`__namedParameters`: { refPath: [AbstractPath](README.md#abstractpath) ; relPath: [AbstractPath](README.md#abstractpath) }): string \| [AbstractPath](README.md#abstractpath)

*Defined in [index.ts:50](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/index.ts#L50)*
*Defined in [index.ts:53](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/index.ts#L53)*

Default resolve implementation
resolve() should handle 3 situations :
Expand All @@ -381,7 +391,7 @@ ___

▸ **loadModule**(`path`: [AbstractPath](README.md#abstractpath), `options?`: [Options](README.md#options)): Promise<[ModuleExport](README.md#moduleexport)\>

*Defined in [index.ts:130](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/index.ts#L130)*
*Defined in [index.ts:152](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/index.ts#L152)*

This is the main function.
This function is intended to be used only to load the entry point of your application.
Expand Down Expand Up @@ -435,7 +445,7 @@ ___

▸ **loadModuleInternal**(`pathCx`: [PathContext](README.md#pathcontext), `options`: [Options](README.md#options)): Promise<[ModuleExport](README.md#moduleexport)\>

*Defined in [tools.ts:262](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/23ba651/src/tools.ts#L262)*
*Defined in [tools.ts:260](https://github.com/FranckFreiburger/vue3-sfc-loader/blob/04817e0/src/tools.ts#L260)*

#### Parameters:

Expand Down
Loading

0 comments on commit 0e57e5c

Please sign in to comment.