@webhandle/initialize-webhandle-component 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# @webhandle/initialize-webhandle-component
+
+Webhandle Components are a way to add services, templates, static files, middleware, or other
+code to a webhandle instance. What the component does, how it does it, and how it exposes
+that functionality is totally up to the component.
+
+There are only three rules:
+
+1. A file will exist at the root of the package, initialize-webhandle-component.mjs, that will
+export a default async function taking a webhandle instance and options as parameters.
+
+```js
+export default async function setup(webhandle, options) {
+	// something here
+}
+```
+
+2. The function is safe to invoke multiple times on the same webhandle instance.
+
+3. The function returns an object which exposes any data or functionality that the 
+component provides. This can be an empty object if there's no exposed functionality.
+
+
+
+The code in this package has some ideas about what exposed functionality looks like and
+how to handle multiple invocations of the function. They are only suggestions and the
+code itself in this package only exists to prevent having to copy the same boilerplate
+over and over again.
+
+## Install
+
+```bash
+npm install @webhandle/initialize-webhandle-component.mjs
+```
+
+
+## Creating a Component
+
+The initialization file can be created for you by running 
+
+```bash
+npx create-initialize-webhandle-component-file
+```
+
+This will create the file `initiailze-webhandle-component.mjs` in the current directory.
+Make sure to go in and change the component name and add the code needed to integrate 
+your functionality.
+
+
+## Using a Component
+
+1. Install that component via npm like:
+
+```bash
+npm install @my/component
+```
+
+2. Import and run the setup function like:
+
+```js
+import setup from "@my/component/initialize-webhandle-component.mjs"
+await setup(myWebhandleInstance, options)
+```
+
+
+## Component Documentation
+
+There's lots of things you'd want to document about the what your component does, but here 
+are the things you probably should mention to help callers access those functions.
+
+On the server side:
+
+1. The services exposed
+2. The events emitted
+3. The static content made available
+4. The templates made available
+
+On the client side:
+
+1. The js modules supplied to client code.
+2. The URLs at which exposed functionality is available. 
+

package/component-manager.mjs

@@ -0,0 +1,49 @@
+import EventEmitter from 'events'
+
+export default class ComponentManager {
+
+	views;
+	templateLoaders;
+	staticPaths;
+	staticServers;
+	sinks;
+	services;
+	routers;
+	events;
+
+	constructor(options) {
+		Object.assign(this, options)
+
+		this.setIfUnset('views', [])
+
+		/* functions which load templates */
+		this.setIfUnset('templateLoaders', [])
+
+		/* info objects which contain static files to server */
+		this.setIfUnset('staticPaths', [])
+
+		/* the servers of files */
+		this.setIfUnset('staticServers', [])
+
+		/* FileSink objects which allow access to static resources */
+		this.setIfUnset('sinks', {})
+
+		/* services created to access and process data */
+		this.setIfUnset('services', {})
+
+		/* handlers for user requests */
+		this.setIfUnset('routers', [])
+
+		/* event emitters for communications between decoupled components */
+		this.setIfUnset('events', {
+			component: new EventEmitter()
+		})
+	}
+
+	setIfUnset(attr, value) {
+		if ((attr in this) === false) {
+			this[attr] = value
+		}
+	}
+
+}

package/create-initialize-webhandle-component-file.mjs

@@ -0,0 +1,32 @@
+#! /usr/local/bin/node
+import fs from "node:fs"
+import path from "node:path"
+
+let filename = 'initialize-webhandle-component.mjs'
+
+let cwd = process.cwd()
+let packageDir = import.meta.dirname
+let outputPath = path.join(cwd, filename)
+let sourceFile = path.join(packageDir, filename)
+fs.stat(outputPath, (err, stats) => {
+	if(err || !stats) {
+		fs.readFile(sourceFile, (err, data) => {
+			if(!err) {
+				data = data.toString()
+
+				// replaces the component name
+				data = data.split('@webhandle/initialize-webhandle-component').join('component' + (new Date().getTime()))
+				
+				// replaces the relative includes at the top
+				data = data.split('"./').join('"@webhandle/initialize-webhandle-component/')
+				fs.writeFile(outputPath, data, (err) => {
+
+				})
+			}
+			else {
+				console.error(err)
+			}
+		})
+
+	}
+})

package/create-initialize-webhandle-component.mjs

@@ -0,0 +1,27 @@
+
+export default function createInitializeWebhandleComponent() {
+
+	const setup = async function initializeWebhandleComponent(webhandle, options) {
+		if (webhandle.id in initializeWebhandleComponent.cache) {
+			return initializeWebhandleComponent.cache[webhandle.id]
+		}
+
+		let config = Object.assign({}, initializeWebhandleComponent.defaultConfig, webhandle.config[initializeWebhandleComponent.componentName], options)
+		webhandle.config[initializeWebhandleComponent.componentName] = config
+		let managementObject = await initializeWebhandleComponent.setup(webhandle, config)
+		managementObject ||= {}
+		initializeWebhandleComponent.cache[webhandle.id] = managementObject
+		webhandle.componentManagers[initializeWebhandleComponent.componentName] = managementObject
+		
+		managementObject.webhandle = webhandle
+		
+		
+
+		return managementObject
+
+	}
+
+	setup.cache = {}
+	setup.defaultConfig = {}
+	return setup
+}

package/initialize-webhandle-component.mjs

@@ -0,0 +1,27 @@
+import createInitializeWebhandleComponent from "./create-initialize-webhandle-component.mjs"
+import ComponentManager from "./component-manager.mjs"
+import path from "node:path"
+
+let initializeWebhandleComponent = createInitializeWebhandleComponent()
+
+initializeWebhandleComponent.componentName = '@webhandle/initialize-webhandle-component'
+initializeWebhandleComponent.componentDir = import.meta.dirname
+initializeWebhandleComponent.defaultConfig = {}
+initializeWebhandleComponent.staticFilePaths = ['public']
+initializeWebhandleComponent.templatePaths = ['views']
+
+initializeWebhandleComponent.setup = async function(webhandle, config) {
+	let manager = new ComponentManager()
+	
+	for(let filePath of initializeWebhandleComponent.staticFilePaths) {
+		manager.staticPaths.push(webhandle.addStaticDir(path.join(initializeWebhandleComponent.componentDir, filePath)))
+	}
+	
+	for(let templatePath of initializeWebhandleComponent.templatePaths) {
+		webhandle.addTemplateDir(path.join(initializeWebhandleComponent.componentDir, templatePath))
+	}
+
+	return manager
+}
+
+export default initializeWebhandleComponent

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@webhandle/initialize-webhandle-component",
+	"version": "1.0.0",
+	"description": "Boilerplate code for a module to add itself to a webhandle instance",
+	"main": "create-initialize-webhandle-component.mjs",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"bin": {
+		"create-initialize-webhandle-component-file": "create-initialize-webhandle-component-file.mjs"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/EmergentIdeas/webhandle-initialize-webhandle-component.git"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"type": "module",
+	"bugs": {
+		"url": "https://github.com/EmergentIdeas/webhandle-initialize-webhandle-component/issues"
+	},
+	"homepage": "https://github.com/EmergentIdeas/webhandle-initialize-webhandle-component#readme"
+	, "files": [
+		"README.md"
+		, "*.mjs"
+	]
+}