resora 0.1.0

package/dist/index.mjs

@@ -0,0 +1,368 @@
+//#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
+export { ApiResource, Resource };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "resora",
+  "version": "0.1.0",
+  "description": "A structured API response layer for Node.js and TypeScript with automatic JSON responses, collection support, and pagination handling.",
+  "keywords": [
+    "api",
+    "resource",
+    "transformer",
+    "laravel",
+    "typescript",
+    "express",
+    "h3",
+    "pagination",
+    "json",
+    "response"
+  ],
+  "homepage": "https://github.com/toneflix/resora",
+  "bugs": {
+    "url": "https://github.com/toneflix/resora/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toneflix/resora.git"
+  },
+  "license": "MIT",
+  "author": "3m1n1nce <3m1n1nce@toneflix.net>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@eslint/markdown": "^7.5.1",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.6",
+    "@types/supertest": "^6.0.3",
+    "@vitest/coverage-v8": "4.0.18",
+    "barrelize": "^1.7.3",
+    "eslint": "^10.0.0",
+    "express": "^5.1.0",
+    "h3": "2.0.1-rc.14",
+    "supertest": "^7.1.1",
+    "tsdown": "^0.20.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.56.0",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitepress": "2.0.0-alpha.16",
+    "vitest": "^4.0.18",
+    "vue": "^3.5.28"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "lint": "eslint",
+    "test": "pnpm vitest",
+    "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"
+  }
+}