resora 1.3.17 → 1.3.18

package/README.md

@@ -223,6 +223,24 @@ It works with:
 
 Adapters can be added without changing application logic.
 
+Framework adapters that own response dispatch can use a non-thenable snapshot:
+
+```ts
+const response = new UserResource(user)
+  .response()
+  .setStatusCode(201)
+  .setHeaders({ 'X-Resource': 'user' })
+  .toResponseData();
+
+return framework.send(response.body, {
+  status: response.status,
+  headers: response.headers,
+});
+```
+
+This preserves transport metadata across async controller boundaries without
+requiring Resora to write to the framework response directly.
+
 ## Plugin System
 
 Resora exposes a first-class plugin registry for opt-in integrations and lifecycle extensions.

package/dist/index.cjs

@@ -1272,6 +1272,7 @@ const resetPluginsForTests = () => {
 var ServerResponse = class {
 	_status = 200;
 	sent = false;
+	prepared = false;
 	headers = {};
 	constructor(response, body) {
 		this.response = response;
@@ -1285,6 +1286,7 @@ var ServerResponse = class {
 	*/
 	setStatusCode(status) {
 		this._status = status;
+		this.prepared = false;
 		return this;
 	}
 	/**
@@ -1295,6 +1297,7 @@ var ServerResponse = class {
 	*/
 	setBody(body) {
 		this.body = body;
+		this.prepared = false;
 		return this;
 	}
 	/**
@@ -1311,8 +1314,8 @@ var ServerResponse = class {
 	* @returns 
 	*/
 	statusText() {
-		if ("statusMessage" in this.response) return this.response.statusMessage;
-		else if ("statusText" in this.response) return this.response.statusText;
+		if (this.response && "statusMessage" in this.response) return this.response.statusMessage;
+		else if (this.response && "statusText" in this.response) return this.response.statusText;
 	}
 	/**
 	* Set a cookie in the response header
@@ -1355,10 +1358,27 @@ var ServerResponse = class {
 	*/
 	#addHeader(key, value) {
 		this.headers[key] = value;
-		if ("headers" in this.response && this.response.headers && typeof this.response.headers.set === "function") this.response.headers.set(key, value);
-		else if ("setHeader" in this.response) this.response.setHeader(key, value);
-		else if ("set" in this.response && typeof this.response.set === "function") this.response.set(key, value);
-		else if ("header" in this.response && typeof this.response.header === "function") this.response.header(key, value);
+		this.prepared = false;
+		if (this.response && "headers" in this.response && this.response.headers && typeof this.response.headers.set === "function") this.response.headers.set(key, value);
+		else if (this.response && "setHeader" in this.response) this.response.setHeader(key, value);
+		else if (this.response && "set" in this.response && typeof this.response.set === "function") this.response.set(key, value);
+		else if (this.response && "header" in this.response && typeof this.response.header === "function") this.response.header(key, value);
+	}
+	/**
+	* Return the finalized response state without dispatching it.
+	*
+	* This is the preferred integration boundary for frameworks that own their
+	* response lifecycle. The returned object is deliberately not thenable.
+	*/
+	toResponseData() {
+		this.#prepare();
+		const statusText = this.statusText();
+		return {
+			body: this.body,
+			status: this._status,
+			...statusText ? { statusText } : {},
+			headers: { ...this.headers }
+		};
 	}
 	/**
 	* Dispatch the current body and apply any deferred transport state.
@@ -1368,17 +1388,15 @@ var ServerResponse = class {
 	*/
 	send(body) {
 		if (this.sent || this.#rawResponseSent()) return this.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 (typeof body !== "undefined") {
+			this.body = body;
+			this.prepared = false;
+		}
+		this.#prepare();
+		if (!this.response) {
+			this.sent = true;
+			return this.body;
+		}
 		if ("send" in this.response && typeof this.response.send === "function") {
 			if ("statusCode" in this.response) this.response.statusCode = this._status;
 			if ("status" in this.response && typeof this.response.status === "function") this.response.status(this._status);
@@ -1386,13 +1404,7 @@ var ServerResponse = class {
 			this.response.__resoraStatus = this._status;
 			this.response.send(this.body);
 			this.sent = true;
-			runPluginHook("afterSend", {
-				response: this,
-				rawResponse: this.response,
-				body: this.body,
-				status: this._status,
-				headers: { ...this.headers }
-			});
+			this.#runAfterSend();
 			return this.body;
 		}
 		if ("status" in this.response && typeof this.response.status === "function") {
@@ -1404,6 +1416,24 @@ var ServerResponse = class {
 			this.response.__resoraStatus = this._status;
 		}
 		this.sent = true;
+		this.#runAfterSend();
+		return this.body;
+	}
+	#prepare() {
+		if (this.prepared) return;
+		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 };
+		this.prepared = true;
+	}
+	#runAfterSend() {
 		runPluginHook("afterSend", {
 			response: this,
 			rawResponse: this.response,
@@ -1411,7 +1441,6 @@ var ServerResponse = class {
 			status: this._status,
 			headers: { ...this.headers }
 		});
-		return this.body;
 	}
 	#rawResponseSent() {
 		const raw = this.response;

package/dist/index.d.cts

@@ -399,6 +399,12 @@ declare class MakeResource extends Command<CliApp> {
 }
 //#endregion
 //#region src/ServerResponse.d.ts
+interface ServerResponseData<R = any> {
+  body: R;
+  status: number;
+  statusText?: string;
+  headers: Record<string, string>;
+}
 /**
  * ServerResponse class to handle HTTP response construction and sending, compatible
  * with both Express and H3 response objects.
@@ -412,9 +418,11 @@ declare class ServerResponse<R extends NonCollectible | Collectible | ResourceDa
   private body;
   private _status;
   private sent;
+  private prepared;
   headers: Record<string, string>;
   constructor(response: H3Event['res'], body: R);
   constructor(response: Response, body: R);
+  constructor(response: undefined, body: R);
   /**
    * Set the HTTP status code for the response
    *
@@ -465,6 +473,13 @@ declare class ServerResponse<R extends NonCollectible | Collectible | ResourceDa
    * @returns The current ServerResponse instance
    */
   header(key: string, value: string): this;
+  /**
+   * Return the finalized response state without dispatching it.
+   *
+   * This is the preferred integration boundary for frameworks that own their
+   * response lifecycle. The returned object is deliberately not thenable.
+   */
+  toResponseData(): ServerResponseData<R>;
   /**
    * Dispatch the current body and apply any deferred transport state.
    *
@@ -1593,4 +1608,4 @@ declare const extractResponseFromCtx: (ctx: unknown) => any | undefined;
  */
 declare const setCtx: (ctx: unknown) => void;
 //#endregion
-export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, ResoraPlugin, ResoraPluginApi, ResoraPluginUtility, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponsePluginEvent, ResponseStructureConfig, SendPluginEvent, SerializePluginEvent, 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, isResoraCollectionLike, 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 };
+export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, ResoraPlugin, ResoraPluginApi, ResoraPluginUtility, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponsePluginEvent, ResponseStructureConfig, SendPluginEvent, SerializePluginEvent, ServerResponse, ServerResponseData, 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, isResoraCollectionLike, 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/dist/index.d.mts

@@ -399,6 +399,12 @@ declare class MakeResource extends Command<CliApp> {
 }
 //#endregion
 //#region src/ServerResponse.d.ts
+interface ServerResponseData<R = any> {
+  body: R;
+  status: number;
+  statusText?: string;
+  headers: Record<string, string>;
+}
 /**
  * ServerResponse class to handle HTTP response construction and sending, compatible
  * with both Express and H3 response objects.
@@ -412,9 +418,11 @@ declare class ServerResponse<R extends NonCollectible | Collectible | ResourceDa
   private body;
   private _status;
   private sent;
+  private prepared;
   headers: Record<string, string>;
   constructor(response: H3Event['res'], body: R);
   constructor(response: Response, body: R);
+  constructor(response: undefined, body: R);
   /**
    * Set the HTTP status code for the response
    *
@@ -465,6 +473,13 @@ declare class ServerResponse<R extends NonCollectible | Collectible | ResourceDa
    * @returns The current ServerResponse instance
    */
   header(key: string, value: string): this;
+  /**
+   * Return the finalized response state without dispatching it.
+   *
+   * This is the preferred integration boundary for frameworks that own their
+   * response lifecycle. The returned object is deliberately not thenable.
+   */
+  toResponseData(): ServerResponseData<R>;
   /**
    * Dispatch the current body and apply any deferred transport state.
    *
@@ -1593,4 +1608,4 @@ declare const extractResponseFromCtx: (ctx: unknown) => any | undefined;
  */
 declare const setCtx: (ctx: unknown) => void;
 //#endregion
-export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, ResoraPlugin, ResoraPluginApi, ResoraPluginUtility, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponsePluginEvent, ResponseStructureConfig, SendPluginEvent, SerializePluginEvent, 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, isResoraCollectionLike, 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 };
+export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, ResoraPlugin, ResoraPluginApi, ResoraPluginUtility, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponsePluginEvent, ResponseStructureConfig, SendPluginEvent, SerializePluginEvent, ServerResponse, ServerResponseData, 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, isResoraCollectionLike, 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/dist/index.mjs

@@ -1243,6 +1243,7 @@ const resetPluginsForTests = () => {
 var ServerResponse = class {
 	_status = 200;
 	sent = false;
+	prepared = false;
 	headers = {};
 	constructor(response, body) {
 		this.response = response;
@@ -1256,6 +1257,7 @@ var ServerResponse = class {
 	*/
 	setStatusCode(status) {
 		this._status = status;
+		this.prepared = false;
 		return this;
 	}
 	/**
@@ -1266,6 +1268,7 @@ var ServerResponse = class {
 	*/
 	setBody(body) {
 		this.body = body;
+		this.prepared = false;
 		return this;
 	}
 	/**
@@ -1282,8 +1285,8 @@ var ServerResponse = class {
 	* @returns 
 	*/
 	statusText() {
-		if ("statusMessage" in this.response) return this.response.statusMessage;
-		else if ("statusText" in this.response) return this.response.statusText;
+		if (this.response && "statusMessage" in this.response) return this.response.statusMessage;
+		else if (this.response && "statusText" in this.response) return this.response.statusText;
 	}
 	/**
 	* Set a cookie in the response header
@@ -1326,10 +1329,27 @@ var ServerResponse = class {
 	*/
 	#addHeader(key, value) {
 		this.headers[key] = value;
-		if ("headers" in this.response && this.response.headers && typeof this.response.headers.set === "function") this.response.headers.set(key, value);
-		else if ("setHeader" in this.response) this.response.setHeader(key, value);
-		else if ("set" in this.response && typeof this.response.set === "function") this.response.set(key, value);
-		else if ("header" in this.response && typeof this.response.header === "function") this.response.header(key, value);
+		this.prepared = false;
+		if (this.response && "headers" in this.response && this.response.headers && typeof this.response.headers.set === "function") this.response.headers.set(key, value);
+		else if (this.response && "setHeader" in this.response) this.response.setHeader(key, value);
+		else if (this.response && "set" in this.response && typeof this.response.set === "function") this.response.set(key, value);
+		else if (this.response && "header" in this.response && typeof this.response.header === "function") this.response.header(key, value);
+	}
+	/**
+	* Return the finalized response state without dispatching it.
+	*
+	* This is the preferred integration boundary for frameworks that own their
+	* response lifecycle. The returned object is deliberately not thenable.
+	*/
+	toResponseData() {
+		this.#prepare();
+		const statusText = this.statusText();
+		return {
+			body: this.body,
+			status: this._status,
+			...statusText ? { statusText } : {},
+			headers: { ...this.headers }
+		};
 	}
 	/**
 	* Dispatch the current body and apply any deferred transport state.
@@ -1339,17 +1359,15 @@ var ServerResponse = class {
 	*/
 	send(body) {
 		if (this.sent || this.#rawResponseSent()) return this.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 (typeof body !== "undefined") {
+			this.body = body;
+			this.prepared = false;
+		}
+		this.#prepare();
+		if (!this.response) {
+			this.sent = true;
+			return this.body;
+		}
 		if ("send" in this.response && typeof this.response.send === "function") {
 			if ("statusCode" in this.response) this.response.statusCode = this._status;
 			if ("status" in this.response && typeof this.response.status === "function") this.response.status(this._status);
@@ -1357,13 +1375,7 @@ var ServerResponse = class {
 			this.response.__resoraStatus = this._status;
 			this.response.send(this.body);
 			this.sent = true;
-			runPluginHook("afterSend", {
-				response: this,
-				rawResponse: this.response,
-				body: this.body,
-				status: this._status,
-				headers: { ...this.headers }
-			});
+			this.#runAfterSend();
 			return this.body;
 		}
 		if ("status" in this.response && typeof this.response.status === "function") {
@@ -1375,6 +1387,24 @@ var ServerResponse = class {
 			this.response.__resoraStatus = this._status;
 		}
 		this.sent = true;
+		this.#runAfterSend();
+		return this.body;
+	}
+	#prepare() {
+		if (this.prepared) return;
+		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 };
+		this.prepared = true;
+	}
+	#runAfterSend() {
 		runPluginHook("afterSend", {
 			response: this,
 			rawResponse: this.response,
@@ -1382,7 +1412,6 @@ var ServerResponse = class {
 			status: this._status,
 			headers: { ...this.headers }
 		});
-		return this.body;
 	}
 	#rawResponseSent() {
 		const raw = this.response;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resora",
-  "version": "1.3.17",
+  "version": "1.3.18",
   "description": "A structured API response layer for Node.js and TypeScript with automatic JSON responses, collection support, and pagination handling.",
   "keywords": [
     "api",