resora 0.2.18 → 1.0.1

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import path, { dirname, join } from "path";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createRequire } from "module";
 import { pathToFileURL } from "url";
 import { Command } from "@h3ravel/musket";
@@ -253,6 +254,8 @@ const getGlobalCursorMeta = () => {
 	return globalCursorMeta;
 };
 let globalRequestUrl;
+let globalCtx;
+const requestContextStore = new AsyncLocalStorage();
 /**
 * Sets the current request URL, used as a fallback for pagination link generation
 * when no explicit path is provided in the pagination data.
@@ -268,7 +271,16 @@ const setRequestUrl = (url) => {
 * @returns The current request URL, or undefined if not set.
 */
 const getRequestUrl = () => {
-	return globalRequestUrl;
+	return requestContextStore.getStore()?.url ?? globalRequestUrl;
+};
+const runWithCtx = (ctx, callback) => {
+	return requestContextStore.run({
+		ctx,
+		url: extractRequestUrl(ctx)
+	}, callback);
+};
+const getCtx = () => {
+	return requestContextStore.getStore()?.ctx ?? globalCtx;
 };
 /**
 * Extracts the request URL pathname (with query string) from an HTTP context.
@@ -330,6 +342,7 @@ const extractResponseFromCtx = (ctx) => {
 * @param ctx An HTTP context `{ req, res }`, Express Request, H3 HTTPEvent, or bare request.
 */
 const setCtx = (ctx) => {
+	globalCtx = ctx;
 	setRequestUrl(extractRequestUrl(ctx));
 };
 
@@ -932,12 +945,12 @@ const resolveAndApply = (imported) => {
 * @returns 
 */
 const loadRuntimeConfigSync = () => {
-	const require = createRequire(import.meta.url);
+	const req = createRequire(import.meta.url);
 	const syncConfigPaths = [path.join(process.cwd(), "resora.config.cjs")];
 	for (const configPath of syncConfigPaths) {
 		if (!existsSync(configPath)) continue;
 		try {
-			resolveAndApply(require(configPath));
+			resolveAndApply(req(configPath));
 			return true;
 		} catch {
 			continue;
@@ -1159,6 +1172,51 @@ var logo_default = String.raw`
  |_|  \_\___||___/\___/|_|  \__,_|                                                                                           
 `;
 
+//#endregion
+//#region src/plugins.ts
+const registeredPlugins = /* @__PURE__ */ new Map();
+const registeredUtilities = /* @__PURE__ */ new Map();
+const getRegisteredPlugins = () => {
+	return Array.from(registeredPlugins.values());
+};
+const registerUtility = (name, utility) => {
+	registeredUtilities.set(name, utility);
+	return utility;
+};
+const getUtility = (name) => {
+	return registeredUtilities.get(name);
+};
+const pluginApi = {
+	runWithCtx,
+	setCtx,
+	getCtx,
+	registerUtility,
+	getUtility,
+	getRegisteredPlugins
+};
+const definePlugin = (plugin) => {
+	return plugin;
+};
+const registerPlugin = (plugins) => {
+	for (const plugin of Array.isArray(plugins) ? plugins : [plugins]) {
+		if (registeredPlugins.has(plugin.name)) continue;
+		registeredPlugins.set(plugin.name, plugin);
+		plugin.setup?.(pluginApi);
+	}
+	return getRegisteredPlugins();
+};
+const runPluginHook = (hook, event) => {
+	for (const plugin of registeredPlugins.values()) {
+		const handler = plugin[hook];
+		if (typeof handler === "function") handler(event, pluginApi);
+	}
+	return event;
+};
+const resetPluginsForTests = () => {
+	registeredPlugins.clear();
+	registeredUtilities.clear();
+};
+
 //#endregion
 //#region src/ServerResponse.ts
 /**
@@ -1264,14 +1322,38 @@ var ServerResponse = class {
 	*/
 	send(body) {
 		if (typeof body !== "undefined") this.body = body;
+		const beforeSend = runPluginHook("beforeSend", {
+			response: this,
+			rawResponse: this.response,
+			body: this.body,
+			status: this._status,
+			headers: { ...this.headers }
+		});
+		this.body = beforeSend.body;
+		this._status = beforeSend.status;
+		this.headers = { ...beforeSend.headers };
 		if ("send" in this.response && typeof this.response.send === "function") {
 			if ("statusCode" in this.response) this.response.statusCode = this._status;
 			const sentResponse = this.response.send(this.body);
 			if (sentResponse && "status" in sentResponse && typeof sentResponse.status === "function") sentResponse.status(this._status);
 			else if ("status" in this.response && typeof this.response.status === "function") this.response.status(this._status);
+			runPluginHook("afterSend", {
+				response: this,
+				rawResponse: this.response,
+				body: this.body,
+				status: this._status,
+				headers: { ...this.headers }
+			});
 			return this.body;
 		}
 		if ("status" in this.response && typeof this.response.status !== "function") this.response.status = this._status;
+		runPluginHook("afterSend", {
+			response: this,
+			rawResponse: this.response,
+			body: this.body,
+			status: this._status,
+			headers: { ...this.headers }
+		});
 		return this.body;
 	}
 	/**
@@ -1370,6 +1452,63 @@ var BaseSerializer = class {
 		return resolveMergeWhen(condition, value);
 	}
 	/**
+	* Apply registered plugins for the serialization process, allowing plugins to 
+	* modify the response body and metadata before the response is sent.
+	* 
+	* @param body 
+	* @returns 
+	*/
+	applySerializePlugins(body) {
+		return runPluginHook("afterSerialize", runPluginHook("beforeSerialize", {
+			serializer: this,
+			serializerType: this.getSerializerType(),
+			resource: this.getResourceForMeta(),
+			body
+		})).body;
+	}
+	/**
+	* Apply registered plugins for the response process, allowing plugins to modify the 
+	* response body, headers, and status before the response is sent.
+	* 
+	* @param input 
+	* @returns 
+	*/
+	applyResponsePlugins(input) {
+		const beforeResponse = runPluginHook("beforeResponse", {
+			serializer: this,
+			serializerType: this.getSerializerType(),
+			rawResponse: input.rawResponse,
+			response: input.response,
+			body: input.body
+		});
+		this.setBody(beforeResponse.body);
+		if (typeof input.response?.setBody === "function") input.response.setBody(beforeResponse.body);
+		const afterResponse = runPluginHook("afterResponse", beforeResponse);
+		this.setBody(afterResponse.body);
+		if (typeof input.response?.setBody === "function") input.response.setBody(afterResponse.body);
+		return afterResponse.body;
+	}
+	/**
+	* Resolve the raw response object from the provided response or the current 
+	* context, allowing plugins to access and modify the raw response before it is sent. 
+	* 
+	* @param response 
+	* @returns 
+	*/
+	resolveRawResponse(response) {
+		if (typeof response !== "undefined") return response;
+		return extractResponseFromCtx(getCtx() ?? this.constructor.ctx);
+	}
+	/**
+	* Dispatch a body to a raw response object when it exposes a send() transport method.
+	*
+	* @param raw
+	* @param body
+	*/
+	sendRawResponseBody(raw, body) {
+		if (raw && typeof raw.send === "function") raw.send(body);
+	}
+	/**
 	* Add additional metadata to the response. If called without arguments.
 	* 
 	* @param meta 
@@ -1417,6 +1556,11 @@ var BaseSerializer = class {
 		this.called.withResponse = true;
 		input.callWithResponse(response, input.rawResponse);
 		if (typeof response?.setBody === "function") response.setBody(input.body());
+		this.applyResponsePlugins({
+			body: input.body(),
+			rawResponse: input.rawResponse,
+			response
+		});
 		return response;
 	}
 	/**
@@ -1441,9 +1585,14 @@ var BaseSerializer = class {
 		}
 		const resolvedBody = input.body();
 		if (typeof response?.setBody === "function") response.setBody(resolvedBody);
-		const resolved = Promise.resolve(resolvedBody).then(input.onfulfilled, input.onrejected);
-		if (typeof response?.send === "function") response.send(resolvedBody);
-		else if (typeof input.rawResponse !== "undefined" && input.sendRawResponse) input.sendRawResponse(input.rawResponse, resolvedBody);
+		const dispatchedBody = this.applyResponsePlugins({
+			body: resolvedBody,
+			rawResponse: input.rawResponse,
+			response
+		});
+		const resolved = Promise.resolve(dispatchedBody).then(input.onfulfilled, input.onrejected);
+		if (typeof response?.send === "function") response.send(dispatchedBody);
+		else if (typeof input.rawResponse !== "undefined" && input.sendRawResponse) input.sendRawResponse(input.rawResponse, dispatchedBody);
 		return resolved;
 	}
 	/**
@@ -1627,6 +1776,9 @@ var GenericResource = class GenericResource extends BaseSerializer {
 	getResourceForMeta() {
 		return this.resource;
 	}
+	getSerializerType() {
+		return "generic";
+	}
 	getPayloadKey() {
 		const { wrap, rootKey, factory } = this.resolveResponseStructure();
 		return factory || !wrap ? void 0 : rootKey;
@@ -1670,6 +1822,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 				...paginationExtras,
 				...customMeta || {}
 			}, rootKey);
+			this.body = this.applySerializePlugins(this.body);
 		}
 		return this;
 	}
@@ -1726,7 +1879,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 	* @returns 
 	*/
 	response(res) {
-		const rawResponse = res ?? this.res ?? GenericResource.ctx?.res ?? GenericResource.ctx;
+		const rawResponse = this.resolveRawResponse(res ?? this.res);
 		return this.runResponse({
 			ensureJson: () => this.json(),
 			rawResponse,
@@ -1763,7 +1916,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? GenericResource.ctx?.res ?? GenericResource.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -1776,7 +1929,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onfulfilled,
 			onrejected
@@ -1792,7 +1945,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? GenericResource.ctx?.res ?? GenericResource.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -1805,7 +1958,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onrejected
 		});
@@ -1820,7 +1973,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? GenericResource.ctx?.res ?? GenericResource.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -1833,7 +1986,7 @@ var GenericResource = class GenericResource extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onfulfilled: onfinally,
 			onrejected: onfinally
@@ -1942,6 +2095,9 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 	getResourceForMeta() {
 		return this.resource;
 	}
+	getSerializerType() {
+		return "collection";
+	}
 	/**
 	* Get the appropriate key for the response payload based on the current response 
 	* structure configuration.
@@ -1991,6 +2147,7 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 				...paginationExtras,
 				...customMeta || {}
 			}, rootKey);
+			this.body = this.applySerializePlugins(this.body);
 		}
 		return this;
 	}
@@ -2041,7 +2198,7 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 	* @returns 
 	*/
 	response(res) {
-		const rawResponse = res ?? this.res ?? ResourceCollection.ctx?.res ?? ResourceCollection.ctx;
+		const rawResponse = this.resolveRawResponse(res ?? this.res);
 		return this.runResponse({
 			ensureJson: () => this.json(),
 			rawResponse,
@@ -2074,15 +2231,15 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 	/**
 	* Promise-like then method to allow chaining with async/await or .then() syntax
 	* 
-	* @param onfulfilled  Callback to handle the fulfilled state of the promise, receiving the response body
-	* @param onrejected  Callback to handle the rejected state of the promise, receiving the error reason
+	* @param onfulfilled  Callback to handle the fulfilled state of the promise
+	* @param onrejected  Callback to handle the rejected state of the promise
 	* @returns A promise that resolves to the result of the onfulfilled or onrejected callback 
 	*/
 	then(onfulfilled, onrejected) {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? ResourceCollection.ctx?.res ?? ResourceCollection.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -2095,7 +2252,7 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onfulfilled,
 			onrejected
@@ -2111,7 +2268,7 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? ResourceCollection.ctx?.res ?? ResourceCollection.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -2124,7 +2281,7 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onrejected
 		});
@@ -2139,7 +2296,7 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? ResourceCollection.ctx?.res ?? ResourceCollection.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -2152,7 +2309,7 @@ var ResourceCollection = class ResourceCollection extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onfulfilled: onfinally,
 			onrejected: onfinally
@@ -2255,6 +2412,9 @@ var Resource = class Resource extends BaseSerializer {
 	getResourceForMeta() {
 		return this.resource;
 	}
+	getSerializerType() {
+		return "resource";
+	}
 	getPayloadKey() {
 		const { wrap, rootKey, factory } = this.resolveResponseStructure();
 		return factory || !wrap ? void 0 : rootKey;
@@ -2288,6 +2448,7 @@ var Resource = class Resource extends BaseSerializer {
 				}
 			});
 			this.body = appendRootProperties(this.body, customMeta, rootKey);
+			this.body = this.applySerializePlugins(this.body);
 		}
 		return this;
 	}
@@ -2341,7 +2502,7 @@ var Resource = class Resource extends BaseSerializer {
 	* @returns 
 	*/
 	response(res) {
-		const rawResponse = res ?? this.res ?? Resource.ctx?.res ?? Resource.ctx;
+		const rawResponse = this.resolveRawResponse(res ?? this.res);
 		return this.runResponse({
 			ensureJson: () => this.json(),
 			rawResponse,
@@ -2378,7 +2539,7 @@ var Resource = class Resource extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? Resource.ctx?.res ?? Resource.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -2391,7 +2552,7 @@ var Resource = class Resource extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onfulfilled,
 			onrejected
@@ -2407,7 +2568,7 @@ var Resource = class Resource extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? Resource.ctx?.res ?? Resource.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -2420,7 +2581,7 @@ var Resource = class Resource extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onrejected
 		});
@@ -2435,7 +2596,7 @@ var Resource = class Resource extends BaseSerializer {
 		return this.runThen({
 			ensureJson: () => this.json(),
 			body: () => this.body,
-			rawResponse: this.res ?? Resource.ctx?.res ?? Resource.ctx,
+			rawResponse: this.resolveRawResponse(this.res),
 			createServerResponse: (raw, body) => {
 				const response = new ServerResponse(raw, body);
 				this.withResponseContext = {
@@ -2448,7 +2609,7 @@ var Resource = class Resource extends BaseSerializer {
 				this.withResponse(response, raw);
 			},
 			sendRawResponse: (raw, body) => {
-				raw.send(body);
+				this.sendRawResponseBody(raw, body);
 			},
 			onfulfilled: onfinally,
 			onrejected: onfinally
@@ -2457,4 +2618,4 @@ var Resource = class Resource extends BaseSerializer {
 };
 
 //#endregion
-export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CliApp, GenericResource, InitCommand, MakeResource, Resource, ResourceCollection, ServerResponse, appendRootProperties, applyRuntimeConfig, buildPaginationExtras, buildResponseEnvelope, createArkormCurrentPageResolver, defineConfig, extractRequestUrl, extractResponseFromCtx, getCaseTransformer, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, getRequestUrl, hasPaginationLink, isArkormLikeCollection, isArkormLikeModel, isPlainObject, loadRuntimeConfig, mergeMetadata, normalizeSerializableData, resetRuntimeConfigForTests, resolveCurrentPage, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, sanitizeConditionalAttributes, setCtx, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, setRequestUrl, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };
+export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CliApp, GenericResource, InitCommand, MakeResource, Resource, ResourceCollection, ServerResponse, appendRootProperties, applyRuntimeConfig, buildPaginationExtras, buildResponseEnvelope, createArkormCurrentPageResolver, defineConfig, definePlugin, extractRequestUrl, extractResponseFromCtx, getCaseTransformer, getCtx, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, getRegisteredPlugins, getRequestUrl, getUtility, hasPaginationLink, isArkormLikeCollection, isArkormLikeModel, isPlainObject, loadRuntimeConfig, mergeMetadata, normalizeSerializableData, registerPlugin, registerUtility, resetPluginsForTests, resetRuntimeConfigForTests, resolveCurrentPage, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, runPluginHook, runWithCtx, sanitizeConditionalAttributes, setCtx, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, setRequestUrl, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resora",
-  "version": "0.2.18",
+  "version": "1.0.1",
   "description": "A structured API response layer for Node.js and TypeScript with automatic JSON responses, collection support, and pagination handling.",
   "keywords": [
     "api",
@@ -76,12 +76,15 @@
   "scripts": {
     "cmd": "tsx src/cli/index.ts",
     "lint": "eslint",
-    "test": "pnpm vitest",
+    "test": "pnpm vitest --run",
+    "test:watch": "pnpm vitest --watch",
     "test:coverage": "pnpm vitest --coverage --watch=false",
     "build": "pnpm tsdown",
     "barrel": "barrelize",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:preview": "vitepress preview docs",
+    "version:packages": "pnpm -r --filter \"@resora/*\" version:patch && git add . && git commit -m \"chore: bump package versions\"",
+    "publish:packages": "pnpm version:packages && pnpm -r --filter \"@arkstack/*\" publish --access public"
   }
 }