wooks 0.0.1-beta.7 → 0.0.1-beta.8

package/README.md

@@ -119,516 +119,6 @@ app.get('with-query', () => {
 })
 ```
 
-## Request
+## Composables
 
-To get a reference to the raw request instance use composable function `useRequest`
-
-You probably don't need a `rawRequest` unless you are developing some new feature. All the base use-cases covered with other composable functions.
-
-```js
-import { useRequest } from '@wooksjs/composables'
-app.get('test', () => {
-    const { rawRequest } = useRequest()
-})
-```
-
-### Request Method, Headers, ...
-
-`useRequest` provides some more shortcuts for useful data
-
-```js
-import { useRequest } from '@wooksjs/composables'
-app.get('test', async () => {
-    const { 
-        url,        // request url      (string) 
-        method,     // request method   (string)
-        headers,    // request headers  (object)
-        rawBody,    // request body     ((): Promise<Buffer>)
-    } = useRequest()
-
-    const body = await rawBody() // body as a Buffer
-})
-```
-
-### Request Cookies
-
-Cookies are not parsed unless requested. Composable function `useCookies` provides cookie getter and raw cookies string.
-
-```js
-import { useCookies } from '@wooksjs/composables'
-app.get('test', async () => {
-    const { 
-        rawCookies, // "cookie" from headers (string | undefined)
-        getCookie,  // cookie getter ((name): string | null)
-    } = useCookies()
-
-    console.log(getCookie('session'))
-    // prints the value of the cookie with the name "session"
-})
-```
-
-### Request Body Parser
-
-`npm install @wooksjs/body`
-
-Function `useBody` provides utilities for getting decoded and parsed body.
-
-Body parser supports json, string, multipart/form-data and application/x-www-form-urlencoded content-types.
-
-Body parser does not parse every request's body. The parsing happens only when you call `parseBody` function.
-
-The request handler is invoked even before the request body was sent to the server.
-
-```js
-import { useBody } from '@wooksjs/body'
-app.post('test', async () => {
-    const {
-        isJson, // checks if content-type is "application/json" : () => boolean;
-        isHtml, // checks if content-type is "text/html" : () => boolean;
-        isXml, // checks if content-type is "application/xml" : () => boolean;
-        isText, // checks if content-type is "text/plain" : () => boolean;
-        isBinary, // checks if content-type is binary : () => boolean;
-        isFormData, // checks if content-type is "multipart/form-data" : () => boolean;
-        isUrlencoded, // checks if content-type is "application/x-www-form-urlencoded" : () => boolean;
-        isCompressed, // checks content-encoding : () => boolean | undefined;
-        contentEncodings, // returns an array of encodings : () => string[];
-        parseBody, // parses body according to content-type : <T = unknown>() => Promise<T>;
-        rawBody, // returns raw body Buffer : () => Promise<Buffer>;
-    } = useBody()
-
-    // the handler got the control, but the body isn't loaded yet
-    //...
-
-    console.log(await parseBody())
-
-    // after `await parseBody()` the body was loaded and parsed
-    // ...
-})
-```
-
-### Request Authorization
-
-`useAuthorization` function provides useful helpers for auth-headers:
-
-```js
-import { useAuthorization } from '@wooksjs/composables'
-app.get('test', async () => {
-    const {
-        authorization,      // the raw value of "authorization" header : string
-        authType,           // the auth type (Bearer/Basic) : string
-        authRawCredentials, // the auth credentials that follow auth type : string
-        isBasic,            // true if authType === 'Basic' : () => boolean
-        isBearer,           // true if authType === 'Bearer' : () => boolean
-        basicCredentials,   // parsed basic auth credentials : () => { username: string, password: string }
-    } = useAuthorization()
-
-    if (isBasic()) {
-        const { username, password } = basicCredentials()
-        console.log({ username, password })
-    } else if (isBearer()) {
-        const token = authRawCredentials
-        console.log({ token })
-    } else {
-        // unknown or empty authorization header
-    }
-})
-```
-
-## Response
-
-The easiest way to respond to the request is to return some value from handler function like this:
-```js
-app.get('string_response', () => {
-    return 'hello world!'
-    // responds with:
-    // 200
-    // Content-Length: ...
-    // Content-Type: text/plain
-    // hello world!
-})
-```
-
-Whatever is returned from the handler is the response. `Content-Type` and `Content-Length` headers will be calculated accordingly.
-
-If a handler returns a json object, it will be stringified and the header `Content-Type` will be set to `application/json` automatically:
-```js
-app.get('json_response', () => {
-    return { value: 'hello world!' }
-    // responds with:
-    // 200
-    // Content-Length: ...
-    // Content-Type: application/json
-    // { "value": "hello world!" }
-})
-```
-
-**Supported response types:**
-1. string   (text/plain, text/html, application/xml - depending on the content)
-2. object/array (application/json)
-3. boolean  (text/plain)
-4. readable stream (you must specify `Content-Type` and `Content-Length` headers yourself)
-
-**Raw Response**: When it is needed to take the full control of the response, use composable function `useResponse`
-
-When you get a raw response instance you take away the control of the response on yourself. The framework will not process the output of the handler in this case.
-
-An example of using raw response instance:
-```js
-import { useResponse } from '@wooksjs/composables'
-app.get('test', () => {
-    const { rawResponse } = useResponse()
-    const res = rawResponse()
-    res.writeHead(200, {})
-    res.end('ok')
-})
-```
-
-If you don't want to take away a responsibility for the response but still need a raw response instance you can use `{ passthrough: true }` as an argument.
-The next example does the same thing as the previous example using `passthrough` options:
-
-```js
-import { useResponse } from '@wooksjs/composables'
-app.get('test', () => {
-    const { rawResponse } = useResponse()
-    const res = rawResponse({ passthrough: true })
-    return 'ok'
-})
-```
-
-### Response Headers
-
-A function `useSetHeaders` provides variety of response headers helpers:
-
-```js
-import { useSetHeaders, contentTypes } from '@wooksjs/composables'
-app.get('test', async () => {
-    const {
-        setHeader,      //sets header: (name: string, value: string | number) => void;
-        removeHeader,   //removes header: (name: string) => void;
-        setContentType, //sets "Content-Type": (value: string) => void;
-        headers,        //Object with response headers: Record<string, string>;
-        enableCors,     //sets "Access-Control-Allow-Origin": (origin?: string) => void;
-    } = useSetHeaders()
-
-    setContentType(contentTypes.application.json)
-    setHeader('server', 'myServer v1.0')
-    enableCors()
-    return '{ "value": "OK" }'
-})
-```
-
-Another hook for set header
-
-```js
-import { useRespHeader } from '@wooksjs/composables'
-app.get('test', async () => {
-    const server = useRespHeader('server')
-    server.value = 'myServer v1.0'
-})
-```
-
-### Response Cookies (Set-Cookie)
-
-A function `useSetCookies` provides variety of set-cookie helpers:
-
-```js
-import { useSetCookies } from '@wooksjs/composables'
-app.get('test', async () => {
-    const {
-        setCookie,      // sets cookie : (name: string, value: string, attrs?) => void;
-        removeCookie,   // removes cookie from setlist : (name: string) => void;
-        clearCookies,   // removes all the cookies from setlist : () => void;
-        cookies,        // returns a value of Set-Cookie header: () => string[];
-    } = useSetCookies()
-
-    setCookie('session', 'value', {
-        expires: '2029-01-01',  // Date | string | number;
-        maxAge:  '1h',          // number | TProstoTimeMultiString;
-        domain:  'my-domain',   // string;
-        path:    '/home',       // string;
-        secure:   true,         // boolean;
-        httpOnly: false,        // boolean;
-        sameSite: true,         // boolean | 'Lax' | 'None' | 'Strict';
-    })
-})
-```
-
-Another hook for set-cookie
-
-```js
-import { useRespCookie } from '@wooksjs/composables'
-app.get('test', async () => {
-    const session = useRespCookie('session')
-    session.value = 'value'
-    session.attrs = {
-        expires: '2029-01-01',  // Date | string | number;
-        maxAge:  '1h',          // number | TProstoTimeMultiString;
-        domain:  'my-domain',   // string;
-        path:    '/home',       // string;
-        secure:   true,         // boolean;
-        httpOnly: false,        // boolean;
-        sameSite: true,         // boolean | 'Lax' | 'None' | 'Strict';        
-    }
-})
-```
-
-### Response Status
-
-It's possible to control the response status via `status` function that is available in `useResponse()`
-
-```js
-import { useResponse } from '@wooksjs/composables'
-app.get('test', async () => {
-    const { status } = useResponse()
-    status(201) // sets status 201 for the response
-    console.log(status()) // when called with no argument returns the status
-    return 'response with status 201'
-})
-```
-
-Another status hook:
-```js
-import { useStatus } from '@wooksjs/composables'
-app.get('test', async () => {
-    const status = useStatus()
-    status.value = 201
-    return 'response with status 201'
-})
-```
-
-### Cache-Control
-
-`useSetCacheControl` function provides helpers for headers responsible for cache control
-
-```js
-import { useSetCacheControl } from '@wooksjs/composables'
-app.get('static/*', () => {
-    const { 
-        setAge,             // sets Age (v: number | TProstoTimeMultiString) => void
-        setExpires,         // sets Expires (v: Date | string | number) => void
-        setPragmaNoCache,   // sets Pragma: no-cache (v: boolean) => void
-        setCacheControl,    // sets Cache-Control (data: TCacheControl) => void
-    } = useSetCacheControl()
-
-    setAge('2h 15m')
-    setExpires('2022-05-05')
-    setCacheControl({
-        mustRevalidate: true,
-        noCache: false,
-        noStore: false,
-        noTransform: true,
-        public: true,
-        private: 'field',
-        proxyRevalidate: true,
-        maxAge: '3h 30m 12s',
-        sMaxage: '2h 27m 54s',
-    })
-})
-```
-
-### Proxy Requests
-
-`npm install @wooksjs/proxy`
-
-Wooks provides support for proxy request/response
-
-```js
-import { useProxy } from '@wooksjs/proxy'
-import { useRequest } from '@wooksjs/composables'
-//...
-app.get('*', async () => {
-    const proxy = useProxy()
-    const { url } = useRequest()
-    const fetchResponse = await proxy('https://www.google.com' + url, {
-        // optional method, be default is set with
-        // the original request method
-        method: 'GET',
-
-        // the next four options help to filter out
-        // request/response headers/cookies
-        // each of the option accepts an object with:
-        // - allow: '*' | (string | RegExp)[] - a list to allow (default '*')
-        // - block: '*' | (string | RegExp)[] - a list to block
-        // - overwrite: Record<string| strgin> | ((data: object) -> object) - object or fn to overwrite data
-        reqHeaders: { block: ['referer'] },
-        reqCookies: { allow: ['cookie-to-pass-downstream'] },
-        resHeaders: { overwrite: { 'x-proxied-by': 'wooks-proxy' } },
-        resCookies: { allow: ['cookie-to-pass-upstream'] },
-
-        // debug: true - will print proxy paths and headers/cookies
-        debug: true,
-    })
-    return fetchResponse // fetch response is supported, the body will be upstreamed
-
-    // > you can also return fully buffered body as Uint8Array
-    // return new Uint8Array(await fetchResponse.arrayBuffer())
-
-    // > or as string
-    // return fetchResponse.text()
-
-    // > or change response before return
-    // const data = await fetchResponse.text() + '<new data>'
-    // return data
-})
-//...
-```
-
-### Serve File (Serve-Static)
-
-`npm install @wooksjs/serve-file`
-
-Function `serveFile` returns a readable stream and prepares all the neccessary response headers (like content-length, content-type etc).
-
-It can handle etag and range as well.
-
-```js
-import { serveFile } from '@wooksjs/serve-file'
-// ...
-serveFile(filePath, options)
-```
-
-**serveFile options**
-```ts
-{
-    // Any header to add
-    headers?: Record<string, string>
-
-    // Cache-Control header
-    cacheControl?: TCacheControl
-
-    // Expires header
-    expires?: Date | string | number
-
-    // when true a header "Pragma: no-cache" will be added
-    pragmaNoCache?: boolean
-
-    // the base directory path
-    baseDir?: string
-
-    // default extension will be added to the filePath
-    defaultExt?: string
-
-    // when true lists files in directory
-    listDirectory?: boolean
-    
-    // put 'index.html'
-    // to automatically serve it from the folder    
-    index?: string              
-}
-```
-
-Built-in file server example:
-
-```js
-import { useRouteParams } from '@wooksjs/composables'
-import { serveFile } from '@wooksjs/serve-file'
-app.get('static/*', () => {
-    const { getRouteParam } = useRouteParams()
-    return serveFile(getRouteParam('*'), { cacheControl: { maxAge: '10m' } })
-})
-```
-
-`cacheControl` here is the same object as used in `useSetCacheControl().setCacheControl({ ... })`
-
-## Error Handling
-
-All the exeptions occured in handler are cought by the framework and interpreted as Server Error 500.
-
-
-```js
-app.get('error', () => {
-    throw new Error('Some Error')
-    // A call of this endpoint will result in
-    // 500 Internal Server Error
-    // "Some Error"
-})
-```
-
-By default the Error Handler renders the response according to the `Accept` request header:
-- if it accepts 'application/json' then the response will be in JSON format
-- else if it accepts 'text/html' then the response will be in HTML format
-- else if it accepts 'text/plain' then the response will be rendered in a plain text
-- else the response will be in JSON format anyways
-
-It's possible to return your own error:
-
-```js
-import { WooksError } from '@wooksjs/composables'
-app.get('error', () => {
-    throw new WooksError('429', 'My Description')
-    // A call of this endpoint will result in
-    // 429 Too Many Requests
-    // "My Description"
-})
-```
-
-In this case if you have an alternative (fallback) handler for the same route the error may not occure, the next handler will be called instead.
-
-As an alternative you may not throw the error but return its instance:
-
-```js
-import { WooksError } from '@wooksjs/composables'
-app.get('error', () => {
-    return new WooksError('429', 'My Description')
-    // A call of this endpoint will result in
-    // 429 Too Many Requests
-    // "My Description"
-})
-```
-
-In this case if you have an alternative (fallback) handler for the same route the error will occure anyways as you explicitly return its instance.
-
-## Alternative (Fallback) Handler
-
-It's possible to assign several handlers for the same route. Every next handler will work as a fallback for the previous one.
-
-The fallback handler is called only when exception is thrown out of the previous handler.
-
-If the previous handler returns an Error Instance then the fallback handler won't be called.
-
-For example you serve files, but for some 'not found' files you want to do something else:
-
-```js
-import { Wooks, useRouteParams } from '@wooksjs/composables'
-import { serveFile } from '@wooksjs/serve-file'
-const app = new Wooks()
-
-app.get('static/*', () => {
-    const { getRouteParam } = useRouteParams()
-    // serveFile will throw 404 error if the file is not found
-    return serveFile(getRouteParam('*'), { maxAge: '10m' })
-})
-
-app.get('static/*', () => {
-    // this handler will be called every time the file is not found
-    return 'Here\'s my fallback response'
-})
-
-app.listen(3000)
-```
-
-In order to prevent the fallback to be invoked you must return an Error Instance explicitly:
-
-```js
-import { Wooks, useRouteParams } from '@wooksjs/composables'
-import { serveFile } from '@wooksjs/serve-file'
-const app = new Wooks()
-
-app.get('static/*', () => {
-    const { getRouteParam } = useRouteParams()
-    try {
-        return serveFile(getRouteParam('*'), { maxAge: '10m' })
-    }
-    catch (e) {
-        // now we catch error and return it explicitly
-        return e
-    }
-})
-
-app.get('static/*', () => {
-    // this handler will be never called now
-    return 'Here\'s my fallback response which is never (ever) called'
-})
-
-app.listen(3000)
-```
+[More details on how to use composables here](https://github.com/wooksjs/composables)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wooks",
-  "version": "0.0.1-beta.7",
+  "version": "0.0.1-beta.8",
   "description": "Web Application Framework with hooks",
   "main": "index.js",
   "module": "dist/wooks.esm-bundler.js",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@prostojs/router": "^0.0.14",
-    "@wooksjs/composables": "^0.0.1-alpha.5"
+    "@wooksjs/composables": "^0.0.1-alpha.8"
   },
   "gitHooks": {
     "commit-msg": "node scripts/verifyCommit.js"
@@ -64,9 +64,9 @@
     "@types/node-fetch": "^2.6.2",
     "@typescript-eslint/eslint-plugin": "^5.42.0",
     "@typescript-eslint/parser": "^5.0.0",
-    "@wooksjs/body": "^0.0.1-alpha.3",
+    "@wooksjs/body": "^0.0.1-alpha.4",
     "@wooksjs/proxy": "^0.0.1-alpha.1",
-    "@wooksjs/serve-file": "^0.0.1-alpha.1",
+    "@wooksjs/serve-file": "^0.0.1-alpha.2",
     "brotli": "^1.3.2",
     "conventional-changelog": "^3.1.24",
     "conventional-changelog-cli": "^2.1.1",