@backan/server - npm Package Compare versions

Comparing version 0.0.17 to 0.0.18

package.json

 {
   "name": "@backan/server",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "type": "module",
@@ -38,3 +38,3 @@ "license": "GPL-3.0",
   "devDependencies": {
-    "@backan/core": "0.0.17"
+    "@backan/core": "0.0.18"
   },
@@ -41,0 +41,0 @@ "dependencies": {

README.md

 # BACKAN - Server
 
-Build the Backan server with zero config.
-
 <!-- PIGEONPOSSE START HEADER -->
@@ -20,3 +18,3 @@
 
-Create endpoints with type validations and OpenApi documentation, safely and quickly.
+[**BACKAN**](https://backan.pigeonposse.com/) Create endpoints with type validations and OpenApi documentation, safely and quickly.
 
@@ -28,4 +26,206 @@
 
+<!-- PIGEONPOSSE START DOCS -->
+Build the `backan` server with zero config.
+
+## 🔑 Installation
+
+```bash [npm]
+npm install @backan/server 
+```
+```bash [pnpm]
+pnpm i @backan/server
+```
+```bash [yarn]
+yarn add @backan/server 
+```
+
+[![NPM Version](https://img.shields.io/npm/v/@backan/server?style=for-the-badge&color=yellow)](https://www.npmjs.com/package/@backan/server)
+
+## 📈 usage
+
+```js
+import {server} from '@backan/server'
+import {App} from 'backan' 
+
+// create backan app
+const app = new App( {
+	version     : '1.0.0',
+	title       : 'BACKAN sample application',
+})
+
+// create server for backan
+server({ app })
+
+```
+
+## ⚙️ Configuration
+
+The `backan` server comes ready to use without any configuration, but this does not mean that we can configure certain aspects of the server if we want.
+
+Here is a list of the available options.
+
+```ts
+/**
+ * Options for server function. 
+ * 
+ */
+type ServerOpts = {
+	/**
+	 * The `backan` app instance. 
+	 *
+	 */
+	app: App<Env>,
+	/**
+	 * The port to start the server on.
+	 *
+	 * @default 80
+	 */
+	port?: number
+	/**
+	 * The hostname to bind the server.
+	 *
+	 * @default 'localhost'
+	 */
+	hostname?: string
+	/**
+	 * The protocol to use. Defaults to 'http' unless the port is 443.
+	 * Note: This will be available soon. Currently this does not modify the port, the service is always on http.
+	 *
+	 * @default 'http'
+	 */
+	protocol?: 'http' | 'https',
+	/**
+	 * If true, automatically find an available port if the specified port is in use.
+	 *
+	 * @default false
+	 */
+	autoPort?: boolean
+	/**
+	 * If true, You can pass the parameters {port,autoPort,hostname,protocol} as flags. Example: ---port=1312 --autoPort.
+	 *
+	 * @default false
+	 */
+	allowFlags?: boolean
+	/**
+	 * Optional callback invoked when the server starts successfully.
+	 */
+	onSuccess?: ( info: ServerInfo ) => Promise<void>
+	/**
+	 * Optional callback invoked when an error occurs.
+	 */
+	onError?: ( opts: {
+		/**
+		 * Server error id.
+		 */
+		id: ServerError, 
+		/**
+		 * Error catched in process.
+		 */
+		error: unknown, 
+		/**
+		 * Data info of server.  
+		 */
+		data: ServerInfo
+	} ) => Promise<void>
+	onExit?: ( opts: {
+		/**
+		 * Data info of server.  
+		 */
+		data: ServerInfo
+	} ) => Promise<void>
+}
+
+/**
+ * Data info of server.
+ *
+ */
+type ServerInfo = {
+	/**
+	 * The server hostname.
+	 *
+	 */
+	hostname: string
+	/**
+	 * The server port.
+	 *
+	 */
+	port: number
+	/**
+	 * The server protocol.
+	 *
+	 */
+	protocol: string
+	/**
+	 * The server url: `${protocol}://${hostname}:${port}`.
+	 *
+	 */
+	url: string
+}
+```
+
+## 💡 Examples
+
+### Zero config
+
+```js
+/**
+ * Start a server with zero config for BACKAN
+ *
+ * @see https://backan.pigeonposse.com/guide/server
+ */
+
+import { server } from '@backan/server'
+import app        from './app.js' // your backan app
+
+await server({ app })
+
+```
+
+### Fully customized
+
+```js
+/**
+ * Start a fully customized server for BACKAN
+ *
+ * @see https://backan.pigeonposse.com/guide/server
+ */
+
+import { server } from '@backan/server'
+import app        from './app.js' // your backan app
+
+await server( {
+	app        : app,
+	hostname   : 'localhost',
+	protocol   : 'http',
+	port       : 1312,
+	autoPort   : true,
+	allowFlags : true,
+	onError    : async ( { id, error } ) => {
+		
+		if( id === 'UNEXPECTED' ) console.error( '🐦💔 UNEXPECTED Error' )
+		else if( id === 'PORTS-NOT-AVAILABLE' ) console.error( '🐦💥🚢 No ports availables' )
+		else if( id === 'PORT-NOT-AVAILABLE' ) console.error( '🐦💥🚢 No port available' )
+		else if( id === 'HOSTNAME-NOT-VALID' ) console.error( '🐦💥🌐 Hostname not available' )
+		console.error( '\n',error )
+	
+	},
+	onSuccess : async ( info ) => {
+
+		console.info( '🐦✅ Server info', info )
+	
+	},
+	onExit : async () => {
+
+		console.warn( '\n\n🐦👋 Fly High Pigeon\n' )
+	
+	},
+} )
+
+```
+<!-- PIGEONPOSSE END DOCS -->
+
 <!-- PIGEONPOSSE START INDEX -->
 
+## More from Backan
+
 - [Documentation](https://backan.pigeonposse.com/)
@@ -32,0 +232,0 @@ - 📚 [Library](https://backan.pigeonposse.com/guide/core)

No alert changes

Improved metrics

Total package byte prevSize

56439

7.32%

Number of lines in readme file

324

161.29%

No dependency changes