resora 0.1.0

package/README.md

@@ -0,0 +1,176 @@
+# Resora
+
+Resora is a structured API response layer for Node.js and TypeScript backends.
+
+It provides a clean, explicit way to transform data into consistent JSON responses and automatically send them to the client. Resora supports single resources, collections, and pagination metadata while remaining framework-agnostic and strongly typed.
+
+Resora is designed for teams that care about long-term maintainability, predictable API contracts, and clean separation of concerns.
+
+---
+
+## What Problem Does Resora Solve?
+
+In most Node.js backends:
+
+- Controllers shape JSON directly
+- Response formats drift over time
+- Pagination logic is duplicated
+- Metadata handling is inconsistent
+
+Resora introduces a dedicated **response transformation layer** that removes these concerns from controllers and centralizes response structure in one place.
+
+---
+
+## Core Capabilities
+
+- Explicit data-to-response transformation
+- Automatic JSON response dispatch
+- First-class collection support
+- Built-in pagination metadata handling
+- Predictable and consistent response contracts
+- Strong TypeScript typing
+- Transport-layer friendly (Express, H3, and others)
+
+---
+
+## Basic Example
+
+### Single Resource
+
+```ts
+import { Resource } from 'resora';
+
+class UserResource extends Resource {
+  data() {
+    return this.toArray();
+  }
+}
+```
+
+```ts
+return new UserResource(user).additional({
+  status: 'success',
+  message: 'User retrieved',
+});
+```
+
+Response:
+
+```json
+{
+  "data": {
+    "id": 1,
+    "name": "John"
+  },
+  "status": "success",
+  "message": "User retrieved"
+}
+```
+
+---
+
+### Collection with Pagination
+
+```ts
+import { ResourceCollection } from 'resora';
+
+class UserCollection<R extends User[]> extends ResourceCollection<R> {
+  collects = UserResource;
+
+  data() {
+    return this.toArray();
+  }
+}
+```
+
+```ts
+return new UserCollection({
+  data: users,
+  pagination: {
+    from: 1,
+    to: 10,
+    perPage: 10,
+    total: 100,
+  },
+}).additional({
+  status: 'success',
+  message: 'Users retrieved',
+});
+```
+
+Response:
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "pagination": {
+      "from": 1,
+      "to": 10,
+      "perPage": 10,
+      "total": 100
+    }
+  },
+  "status": "success",
+  "message": "Users retrieved"
+}
+```
+
+---
+
+## Architectural Positioning
+
+Resora sits **between your application logic and the HTTP layer**.
+
+- Controllers handle request flow
+- Services handle business logic
+- Resora handles response structure
+
+This separation ensures:
+
+- Stable API contracts
+- Minimal controller logic
+- Clear ownership of response shape
+
+---
+
+## Design Principles
+
+- Explicit over implicit behavior
+- Separation of concerns
+- Minimal abstraction cost
+- Strong typing as a first-class feature
+- Framework independence
+
+---
+
+## Framework Compatibility
+
+Resora is not tied to a specific HTTP framework.
+
+It works with:
+
+- Express
+- H3
+- Any application or framework that supports Connect-style middleware
+
+Adapters can be added without changing application logic.
+
+---
+
+## When to Use Resora
+
+Resora is a good fit if you:
+
+- Build APIs with long-term maintenance in mind
+- Care about response consistency across teams
+- Want pagination and metadata handled once
+- Prefer explicit structure over ad-hoc JSON responses
+
+It is intentionally not opinionated about routing, validation, or persistence.
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,371 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/ApiResource.ts
+/**
+* ApiResource function to return the Resource instance
+* 
+* @param instance Resource instance
+* @returns Resource instance
+*/
+function ApiResource(instance) {
+	return instance;
+}
+
+//#endregion
+//#region src/ServerResponse.ts
+var ServerResponse = class {
+	_status = 200;
+	headers = {};
+	constructor(response, body) {
+		this.response = response;
+		this.body = body;
+	}
+	/**
+	* Set the HTTP status code for the response
+	* 
+	* @param status 
+	* @returns The current ServerResponse instance
+	*/
+	setStatusCode(status) {
+		this._status = status;
+		if ("status" in this.response && typeof this.response.status === "function") this.response.status(status);
+		else if ("status" in this.response) this.response.status = status;
+		return this;
+	}
+	/**
+	* Get the current HTTP status code for the response
+	* 
+	* @returns 
+	*/
+	status() {
+		return this._status;
+	}
+	/**
+	* Get the current HTTP status text for the response
+	* 
+	* @returns 
+	*/
+	statusText() {
+		if ("statusMessage" in this.response) return this.response.statusMessage;
+		else if ("statusText" in this.response) return this.response.statusText;
+	}
+	/**
+	* Set a cookie in the response header
+	* 
+	* @param name The name of the cookie
+	* @param value The value of the cookie
+	* @param options Optional cookie attributes (e.g., path, domain, maxAge)
+	* @returns The current ServerResponse instance
+	*/
+	setCookie(name, value, options) {
+		this.#addHeader("Set-Cookie", `${name}=${value}; ${Object.entries(options || {}).map(([key, val]) => `${key}=${val}`).join("; ")}`);
+		return this;
+	}
+	/**
+	* Convert the resource to a JSON response body
+	* 
+	* @param headers Optional headers to add to the response
+	* @returns The current ServerResponse instance
+	*/
+	setHeaders(headers) {
+		for (const [key, value] of Object.entries(headers)) this.#addHeader(key, value);
+		return this;
+	}
+	/**
+	* Add a single header to the response
+	* 
+	* @param key The name of the header
+	* @param value The value of the header
+	* @returns The current ServerResponse instance
+	*/
+	header(key, value) {
+		this.#addHeader(key, value);
+		return this;
+	}
+	/**
+	* Add a single header to the response
+	* 
+	* @param key The name of the header
+	* @param value The value of the header
+	*/
+	#addHeader(key, value) {
+		this.headers[key] = value;
+		if ("headers" in this.response) this.response.headers.set(key, value);
+		else if ("setHeader" in this.response) this.response.setHeader(key, value);
+	}
+	/**
+	* 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
+	* @returns A promise that resolves to the result of the onfulfilled or onrejected callback 
+	*/
+	then(onfulfilled, onrejected) {
+		const resolved = Promise.resolve(this.body).then(onfulfilled, onrejected);
+		if ("send" in this.response) this.response.send(this.body);
+		return resolved;
+	}
+	/**
+	* Promise-like catch method to handle rejected state of the promise
+	* 
+	* @param onrejected 
+	* @returns 
+	*/
+	catch(onrejected) {
+		return this.then(void 0, onrejected);
+	}
+	/**
+	* Promise-like finally method to handle cleanup after promise is settled
+	* 
+	* @param onfinally 
+	* @returns 
+	*/
+	finally(onfinally) {
+		return this.then(onfinally, onfinally);
+	}
+};
+
+//#endregion
+//#region src/ResourceCollection.ts
+/**
+* ResourceCollection class to handle API resource transformation and response building for collections
+*/
+var ResourceCollection = class {
+	body = { data: [] };
+	resource;
+	collects;
+	called = {};
+	constructor(rsc, res) {
+		this.res = res;
+		this.resource = rsc;
+	}
+	/**
+	* Get the original resource data
+	*/
+	data() {
+		return this.toArray();
+	}
+	/**
+	* Convert resource to JSON response format
+	* 
+	* @returns 
+	*/
+	json() {
+		if (!this.called.json) {
+			this.called.json = true;
+			let data = this.data();
+			if (this.collects) data = data.map((item) => new this.collects(item).data());
+			this.body = { data };
+			if (!Array.isArray(this.resource)) {
+				if (this.resource.pagination && this.resource.cursor) this.body.meta = {
+					pagination: this.resource.pagination,
+					cursor: this.resource.cursor
+				};
+				else if (this.resource.pagination) this.body.meta = { pagination: this.resource.pagination };
+				else if (this.resource.cursor) this.body.meta = { cursor: this.resource.cursor };
+			}
+		}
+		return this;
+	}
+	/**
+	* Flatten resource to return original data
+	*
+	* @returns
+	*/
+	toArray() {
+		this.called.toArray = true;
+		this.json();
+		return Array.isArray(this.resource) ? [...this.resource] : [...this.resource.data];
+	}
+	/**
+	* Add additional properties to the response body
+	* 
+	* @param extra  Additional properties to merge into the response body
+	* @returns 
+	*/
+	additional(extra) {
+		this.called.additional = true;
+		this.json();
+		delete extra.cursor;
+		delete extra.pagination;
+		if (extra.data && Array.isArray(this.body.data)) this.body.data = [...this.body.data, ...extra.data];
+		this.body = {
+			...this.body,
+			...extra
+		};
+		return this;
+	}
+	response(res) {
+		this.called.toResponse = true;
+		return new ServerResponse(res ?? this.res, this.body);
+	}
+	setCollects(collects) {
+		this.collects = collects;
+		return this;
+	}
+	/**
+	* 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
+	* @returns A promise that resolves to the result of the onfulfilled or onrejected callback 
+	*/
+	then(onfulfilled, onrejected) {
+		this.called.then = true;
+		this.json();
+		const resolved = Promise.resolve(this.body).then(onfulfilled, onrejected);
+		if (this.res) this.res.send(this.body);
+		return resolved;
+	}
+	/**
+	* Promise-like catch method to handle rejected state of the promise
+	* 
+	* @param onrejected 
+	* @returns 
+	*/
+	catch(onrejected) {
+		return this.then(void 0, onrejected);
+	}
+	/**
+	* Promise-like finally method to handle cleanup after promise is settled
+	* 
+	* @param onfinally 
+	* @returns 
+	*/
+	finally(onfinally) {
+		return this.then(onfinally, onfinally);
+	}
+};
+
+//#endregion
+//#region src/Resource.ts
+/**
+* Resource class to handle API resource transformation and response building
+*/
+var Resource = class {
+	body = { data: {} };
+	resource;
+	called = {};
+	constructor(rsc, res) {
+		this.res = res;
+		this.resource = rsc;
+		/**
+		* Copy properties from rsc to this instance for easy 
+		* access, but only if data is not an array
+		*/
+		if (!Array.isArray(this.resource.data ?? this.resource)) {
+			for (const key of Object.keys(this.resource.data ?? this.resource)) if (!(key in this)) Object.defineProperty(this, key, {
+				enumerable: true,
+				configurable: true,
+				get: () => {
+					return this.resource.data?.[key] ?? this.resource[key];
+				},
+				set: (value) => {
+					if (this.resource.data && this.resource.data[key]) this.resource.data[key] = value;
+					else this.resource[key] = value;
+				}
+			});
+		}
+	}
+	/**
+	* Create a ResourceCollection from an array of resource data or a Collectible instance
+	* 
+	* @param data 
+	* @returns 
+	*/
+	static collection(data) {
+		return new ResourceCollection(data).setCollects(this);
+	}
+	/**
+	* Get the original resource data
+	*/
+	data() {
+		return this.toArray();
+	}
+	/**
+	* Convert resource to JSON response format
+	* 
+	* @returns 
+	*/
+	json() {
+		if (!this.called.json) {
+			this.called.json = true;
+			const resource = this.data();
+			let data = Array.isArray(resource) ? [...resource] : { ...resource };
+			if (typeof data.data !== "undefined") data = data.data;
+			this.body = { data };
+		}
+		return this;
+	}
+	/**
+	* Flatten resource to array format (for collections) or return original data for single resources
+	*
+	* @returns
+	*/
+	toArray() {
+		this.called.toArray = true;
+		this.json();
+		let data = Array.isArray(this.resource) ? [...this.resource] : { ...this.resource };
+		if (!Array.isArray(data) && typeof data.data !== "undefined") data = data.data;
+		return data;
+	}
+	/**
+	* Add additional properties to the response body
+	* 
+	* @param extra  Additional properties to merge into the response body
+	* @returns 
+	*/
+	additional(extra) {
+		this.called.additional = true;
+		this.json();
+		if (extra.data) this.body.data = Array.isArray(this.body.data) ? [...this.body.data, ...extra.data] : {
+			...this.body.data,
+			...extra.data
+		};
+		this.body = {
+			...this.body,
+			...extra
+		};
+		return this;
+	}
+	response(res) {
+		this.called.toResponse = true;
+		return new ServerResponse(res ?? this.res, this.body);
+	}
+	/**
+	* 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
+	* @returns A promise that resolves to the result of the onfulfilled or onrejected callback 
+	*/
+	then(onfulfilled, onrejected) {
+		this.called.then = true;
+		this.json();
+		const resolved = Promise.resolve(this.body).then(onfulfilled, onrejected);
+		if (this.res) this.res.send(this.body);
+		return resolved;
+	}
+	/**
+	* Promise-like catch method to handle rejected state of the promise
+	* 
+	* @param onrejected 
+	* @returns 
+	*/
+	catch(onrejected) {
+		return this.then(void 0, onrejected);
+	}
+	/**
+	* Promise-like finally method to handle cleanup after promise is settled
+	* 
+	* @param onfinally 
+	* @returns 
+	*/
+	finally(onfinally) {
+		return this.then(onfinally, onfinally);
+	}
+};
+
+//#endregion
+exports.ApiResource = ApiResource;
+exports.Resource = Resource;