@momsfriendlydevco/cowboy 1.3.0 → 1.4.1

package/eslint.config.js

@@ -0,0 +1,10 @@
+import {defineConfig, globalIgnores} from "eslint/config";
+import RulesMFDC from '@momsfriendlydevco/eslint-config';
+
+export default defineConfig([
+	globalIgnores([
+		'.*',
+		'node_modules/',
+	]),
+	...RulesMFDC,
+])

package/lib/cowboy.js

@@ -25,10 +25,11 @@ export class Cowboy {
 	* General settings for this Cowboy instance
 	*
 	* @type {Object}
+	* @property {Boolean|'VAR'} scheduler Add a generic `/__scheduled` endpoint to execute any queued scheduler. If value is `'VAR'` this will only apply if the env `COWBOY_SCHEDULER` is set and truthy
 	* @property {Function} pathTidy Additional tidyup for server request paths, useful if the API does not live at the server root. Defaults to removing a "/api/:worker/" prefix
 	*/
 	settings = {
-		patchAxios: true,
+		scheduler: 'VAR',
 		pathTidy(path) {
 			return path
 				.replace(/^\/api\/\w+/, '/')
@@ -39,7 +40,7 @@ export class Cowboy {
 
 	/**
 	* List of middleware which will be called on all matching routes
-	* @type Array<CowboyMiddleware>
+	* @type {Array<CowboyMiddleware>}
 	*/
 	earlyMiddleware = [];
 
@@ -62,9 +63,9 @@ export class Cowboy {
 	* Queue up a middleware path
 	* All given middleware is called in sequence, if middleware
 	*
-	* @param {String|Array<String>} methods A method matcher or array of available methods
+	* @param {String|Array<String>} methods A method matcher or array of available methods in upper-case
 	* @param {String|RegExp|Array<String|RegExp>} paths A prefix path to match
-	* @param {CowboyMiddleware} middleware... Middleware to call in sequence
+	* @param {CowboyMiddleware...} middleware Middleware to call in sequence
 	*
 	* @returns {Cowboy} This chainable Cowboy router instance
 	*/
@@ -107,7 +108,8 @@ export class Cowboy {
 
 	/**
 	* Action an incoming route by resolving + walking down its middleware chain
-	* @param {CloudflareRequest} req The incoming request
+	*
+	* @param {CloudflareRequest} cfReq The incoming request
 	* @param {Object} [env] Optional environment passed from Cloudflare
 	* @returns {Promise<CowboyResponse>} A promise which will eventually resolve when all middleware completes
 	*/
@@ -117,6 +119,46 @@ export class Cowboy {
 		if (env.COWBOY_DEBUG)
 			debug.enabled = true;
 
+		if ( // Setup scheduler endpoint if this is the first fetch() hit were we can access the `env` state
+			!this._schedulerSetup
+			&& (
+				this.settings.scheduler === true
+				|| (
+					this.settings.scheduler == 'VAR'
+					&& env.COWBOY_SCHEDULER
+				)
+			)
+		) {
+			console.log('Scheduler setup against /__scheduled');
+			this._schedulerSetup = true;
+
+			// Find first GET operation
+			let routeIndex = this.routes.findIndex(r => r.methods.some(m => m == 'GET'));
+			if (routeIndex < 0) routeIndex = this.routes.length; // If no GETS, assume end position
+
+			// Splice into position before first GET
+			let matcher = compileRoutePaths('/__scheduled');
+			this.routes.splice(routeIndex, 0, {
+				methods: ['GET'],
+				paths: matcher.paths,
+				matcher,
+				middleware: [
+					async (req, res, env) => {
+						debug('Executing schedule handler');
+						if (!this.schedule.handler) return res.status(404).send('No scheduler installed');
+
+						try {
+							let result = await this.schedule.handler.call(this, {}, env, {});
+							res.send(result);
+						} catch (e) {
+							res.status(400).send(`Scheduler threw error: ${e.toString()}`);
+						}
+					},
+				]
+			});
+		}
+
+
 		// Create basic [req]uest / [res]ponse objects
 		let req = new CowboyRequest(cfReq, {
 			router: this,
@@ -173,10 +215,13 @@ export class Cowboy {
 	* @param {CloudflareEvent} event The Cloudflare event context passed
 	* @param {Object} env Environment variables
 	* @param {CloudflareContext} ctx The Cloudflare context to respond to
+	*
+	* @returns {Cowboy} This chainable Cowboy router instance
 	*/
 	scheduled(event, env, ctx) {
 		if (!this.schedule.handler) throw new Error('Attemped to access Cowboy.scheduled without first calling .schedule() to set something up!');
-		return this.schedule.handler.call(this, event, env, ctx);
+		this.schedule.handler.call(this, event, env, ctx);
+		return this;
 	}
 
 
@@ -185,7 +230,7 @@ export class Cowboy {
 	* This function exists as an easier way to remap body contents without
 	*
 	* @param {String} url The URL path to call
-	* @param {Object} request Additional request options
+	* @param {Object} options Additional request options
 	* @param {Object} env The environment object to use
 	*
 	* @returns {CloudflareResponse} The returned CloudflareResponse object
@@ -287,7 +332,7 @@ export class Cowboy {
 	/**
 	* Handle cron job scheduling
 	*
-	* @param {Function} cb The callback to install for all scheduled events. Called as `(event:CloudflareEvent, env:Object, ctx:CloudflareContext)`
+	* @param {Function} handler The callback to install for all scheduled events. Called as `(event:CloudflareEvent, env:Object, ctx:CloudflareContext)`
 	* @returns {Cowboy} This chainable Cowboy router instance
 	*/
 	schedule(handler) {
@@ -306,10 +351,6 @@ export class Cowboy {
 		if (this.doneInit) return this; // Already completed init
 		debug('INIT!');
 
-		if (this.settings.patchAxios) {
-			// TODO: Patch Axios somehow
-			// axios.defaults.adapter = axiosFetchAdapter;
-		}
 		return this;
 	}
 }
@@ -317,6 +358,9 @@ export class Cowboy {
 
 /**
 * Wrap an incoming Wrangler request
+*
+* @param {Object} [options] Additional initalization options to use in the Constructor
+*
 * @returns {Object} A Wrangler compatible object
 */
 export default function cowboy(options) {

package/lib/debug.js

@@ -1,3 +1,9 @@
+/**
+* Wrapper around the debug instance
+* This function will only output when cowboy is in debug mode
+*
+* @param {*...} msg Message component to show
+*/
 export default function CowboyDebug(...msg) {
 	if (!CowboyDebug.enabled) return;
 	console.log('COWBOY-DEBUG', ...msg.map(m =>

package/lib/request.js

@@ -2,7 +2,7 @@ import debug from '#lib/debug';
 
 /**
 * Tiny wrapper around Wrangler to wrap its default Request object in an Express-like structure
-* @extends CloudflareRequest
+* @augments {CloudflareRequest}
 */
 export default class CowboyRequest {
 	/**

package/lib/response.js

@@ -52,6 +52,7 @@ export default class CowboyResponse {
 	send(data, end = true) {
 		if (this.code === null) this.code = 200; // Assume OK if not told otherwise
 
+		// eslint-disable-next-line unicorn/prefer-ternary
 		if (
 			typeof data == 'string'
 			|| data instanceof FormData
@@ -125,7 +126,7 @@ export default class CowboyResponse {
 		console.log('Response', JSON.stringify({
 			...cfOptions,
 			body:
-				typeof this.body == 'string' && this.body.length > 30 ? this.body.substr(0, 50) + '…'
+				typeof this.body == 'string' && this.body.length > 30 ? this.body.substr(0, 50) + '…' // eslint-disable-line unicorn/prefer-string-slice
 				: this.body,
 		}, null, '\t'));
 		return new this.CloudflareResponse(this.body, cfOptions);

package/lib/testkit.js

@@ -19,6 +19,7 @@ export let worker;
 * @param {Axios} [options.axios] Axios instance to mutate with the base URL, if specified
 * @param {Boolean} [options.server=true] Initialize a local server - disable this if you're running your own
 * @param {Boolean} [options.debug=false] Force debug as if `DEBUG=cowboy` was set
+* @param {Boolean} [options.scheduler=false] Bind any scedhuler callback to `/__scheduled`
 * @param {Function} [options.logOutput] Function to wrap STDOUT output. Called as `(line:String)`
 * @param {Function} [options.logOutputErr] Function to wrap STDERR output. Called as `(line:String)`
 * @param {String} [options.host='127.0.0.1'] Host to run Wrangler on
@@ -32,6 +33,7 @@ export function start(options) {
 		axios: null,
 		server: true,
 		debug: false,
+		scheduler: false,
 		logOutput: output => console.log('WRANGLER>', output),
 		logOutputErr: output => console.log('WRANGLER!', output),
 		host: '127.0.0.1',
@@ -70,6 +72,9 @@ export function start(options) {
 					...(debug.enabled ? [
 						'--var=COWBOY_DEBUG:1'
 					]: []),
+					...(settings.scheduler ? [
+						'--var=COWBOY_SCHEDULER:1'
+					]: []),
 				]);
 
 				worker.stdout.on('data', data => {
@@ -109,7 +114,6 @@ export function start(options) {
 
 /**
 * Stop background wrangler instances
-* @returns {Promise} A promise which resolves when the operation has completed
 */
 export function stop() {
 	if (!worker) return; // Worker not active anyway
@@ -125,11 +129,13 @@ export function stop() {
 */
 export function cowboyMocha(options) {
 
+	// eslint-disable-next-line no-undef
 	before('start cowboy/testkit', function() {
 		this.timeout(30 * 1000);
 		return start(options);
 	});
 
+	// eslint-disable-next-line no-undef
 	after('stop cowboy/testkit', function() {
 		this.timeout(5 * 1000);
 		return stop();

package/middleware/cors.js

@@ -2,26 +2,30 @@
 * Register a generic middleware to handle CORS requests
 *
 * @param {Object} [options] Additional options to mutate behaviour
-* @param {Boolean} [options.attachOptions=true] Attach an `options` method against all routes that don't already have one to pass the CORS pre-flight check
-* @param {Object} [options.headers] Generic CORS headers to inject
+* @param {Boolean} [options.attachOptions=true] Automatically attach an `OPTIONS` method against all routes that don't already have one to pass the CORS pre-flight check
+* @param {String} [options.origin='*'] Origin URL to allow
+* @param {String} [options.headers='*'] Headers to allow
+* @param {Array<String>} [options.methods=['GET','POST','OPTIONS']] Allowable HTTP methods to add CORS to
 *
 * @returns {CowboyMiddleware}
 */
 export default function CowboyMiddlewareCORS(options) {
 	let settings = {
 		attachOptions: true,
-		headers: {
-			'Access-Control-Allow-Origin': '*',
-			'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-			'Access-Control-Allow-Headers': '*',
-			'Content-Type': 'application/json;charset=UTF-8',
-		},
+		origin: '*',
+		headers: '*',
+		methods: ['GET', 'POST', 'OPTIONS'],
 		...options,
 	};
 
 	return (req, res) => {
 		// Always inject CORS headers
-		res.set(settings.headers);
+		res.set({
+			'Access-Control-Allow-Origin': settings.origin,
+			'Access-Control-Allow-Methods': settings.methods.join(', '),
+			'Access-Control-Allow-Headers': settings.headers,
+			'Content-Type': 'application/json;charset=UTF-8',
+		});
 
 		// Inject various OPTIONS endpoints for CORS pre-flight
 		if (settings.attachOptions && !req.router.loadedCors) {

package/middleware/devOnly.js

@@ -6,7 +6,7 @@
 */
 export default function CowboyMiddlewareDevOnly() {
 	return (req, res, env) => {
-		const isDev = self.ENVIRONMENT === 'development';
+		const isDev = env.ENVIRONMENT === 'development';
 
 		if (!isDev) return res
 			.status(403)

package/middleware/parseJwt.js

@@ -3,6 +3,8 @@
 *
 * @param {Object} [options] Additional options to mutate behaviour
 * @param {Function} [options.isJwt] Async function, called as `(req, res)` to determine if the input is a JWT payload, defaults to checking the content-type header
+*
+* @returns {CowboyMiddleware}
 */
 export default function CowboyMiddlewareParseJwt(options) {
 	let settings = {
@@ -13,7 +15,7 @@ export default function CowboyMiddlewareParseJwt(options) {
 	};
 
 	return async (req, res) => {
-		if (await !settings.isJwt(req, res)) return;
+		if (!(await settings.isJwt(req, res))) return;
 
 		const base64 = req.text.split('.')[1].replace(/-/g, '+').replace(/_/g, '/');
 		req.body = JSON.parse(atob(base64));

package/middleware/validate.js

@@ -4,7 +4,7 @@ import joyful from '@momsfriendlydevco/joyful';
 * Run a Joi / Joyful validation function against a specific subkey within `req
 *
 * @param {String} subkey The subkey to run against
-* @param {Function|Object} Callback to use with Joyful to validate with
+* @param {Function|Object} validator Callback to use with Joyful to validate with
 * @returns {Void} Either a successful middleware cycle (if validation succeeds) or a call to `res.status(400)` if failed
 */
 export default function CowboyMiddlewareValidate(subkey, validator) {

package/middleware/validateBody.js

@@ -1,5 +1,11 @@
 import CowboyMiddlewareValidate from '#middleware/validate';
 
+/**
+* Shorthand middleware to apply validation to the request body (`req.body`) object
+*
+* @param {Function|Object} validator Callback to use with Joyful to validate with
+* @returns {CowboyMiddleware}
+*/
 export default function CowboyMiddlewareValidateBody(validator) {
 	return CowboyMiddlewareValidate('body', validator);
 }

package/middleware/validateHeaders.js

@@ -1,5 +1,11 @@
 import CowboyMiddlewareValidate from '#middleware/validate';
 
+/**
+* Shorthand middleware to apply validation to the headers (`req.headers`) object
+*
+* @param {Function|Object} validator Callback to use with Joyful to validate with
+* @returns {CowboyMiddleware}
+*/
 export default function CowboyMiddlewareValidateHeaders(validator) {
 	return CowboyMiddlewareValidate('headers', validator);
 }

package/middleware/validateParams.js

@@ -1,5 +1,11 @@
 import CowboyMiddlewareValidate from '#middleware/validate';
 
+/**
+* Shorthand middleware to apply validation to the parameters (`req.params`) object
+*
+* @param {Function|Object} validator Callback to use with Joyful to validate with
+* @returns {CowboyMiddleware}
+*/
 export default function CowboyMiddlewareValidateParams(validator) {
 	return CowboyMiddlewareValidate('params', validator);
 }

package/middleware/validateQuery.js

@@ -1,5 +1,11 @@
 import CowboyMiddlewareValidate from '#middleware/validate';
 
+/**
+* Shorthand middleware to apply validation to the query (`req.query`) object
+*
+* @param {Function|Object} validator Callback to use with Joyful to validate with
+* @returns {CowboyMiddleware}
+*/
 export default function CowboyMiddlewareValidateQuery(validator) {
 	return CowboyMiddlewareValidate('query', validator);
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@momsfriendlydevco/cowboy",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Wrapper around Cloudflare Wrangler to provide a more Express-like experience",
   "scripts": {
-    "lint": "eslint ."
+    "lint": "eslint"
   },
   "keywords": [
     "wrangler"
@@ -40,18 +40,7 @@
     "toml": "^3.0.0"
   },
   "devDependencies": {
-    "@momsfriendlydevco/eslint-config": "^1.0.7",
-    "eslint": "^8.51.0"
-  },
-  "eslintConfig": {
-    "extends": "@momsfriendlydevco",
-    "env": {
-      "es6": true,
-      "node": true
-    },
-    "parserOptions": {
-      "ecmaVersion": 13,
-      "sourceType": "module"
-    }
+    "@momsfriendlydevco/eslint-config": "^2.3.1",
+    "eslint": "^9.33.0"
   }
 }