resora 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,11 @@
 # Resora
 
+[![NPM Downloads](https://img.shields.io/npm/dt/resora.svg)](https://www.npmjs.com/package/resora)
+[![npm version](https://img.shields.io/npm/v/resora.svg)](https://www.npmjs.com/package/resora)
+[![License](https://img.shields.io/npm/l/resora.svg)](https://github.com/toneflix/resora/blob/main/LICENSE)
+[![CI](https://github.com/toneflix/resora/actions/workflows/ci.yml/badge.svg)](https://github.com/toneflix/resora/actions/workflows/ci.yml)
+[![Deploy Docs](https://github.com/toneflix/resora/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/toneflix/resora/actions/workflows/deploy-docs.yml)
+
 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.

package/bin/index.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env ts-node
+import path, { dirname, join } from "path";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { Command, Kernel } from "@h3ravel/musket";
+
+//#region src/utility.ts
+const __dirname = /* @__PURE__ */ path.dirname(fileURLToPath(import.meta.url));
+let stubsDir = path.resolve(__dirname, "../node_modules/resora/stubs");
+if (!existsSync(stubsDir)) stubsDir = path.resolve(__dirname, "../stubs");
+/**
+* Define the configuration for the package
+* 
+* @param userConfig  The user configuration to override the default configuration
+* @returns The merged configuration object
+*/
+const defineConfig = (userConfig = {}) => {
+	return Object.assign({
+		resourcesDir: "src/resources",
+		stubsDir,
+		stubs: {
+			resource: "resource.stub",
+			collection: "resource.collection.stub"
+		}
+	}, userConfig, { stubs: Object.assign({
+		resource: "resource.stub",
+		collection: "resource.collection.stub"
+	}, userConfig.stubs || {}) });
+};
+
+//#endregion
+//#region src/cli/actions.ts
+var CliApp = class {
+	command;
+	config = {};
+	constructor(config = {}) {
+		this.config = defineConfig(config);
+		const require = createRequire(import.meta.url);
+		const possibleConfigPaths = [
+			join(process.cwd(), "resora.config.ts"),
+			join(process.cwd(), "resora.config.js"),
+			join(process.cwd(), "resora.config.cjs")
+		];
+		for (const configPath of possibleConfigPaths) if (existsSync(configPath)) try {
+			const { default: userConfig } = require(configPath);
+			Object.assign(this.config, defineConfig(userConfig));
+			break;
+		} catch (e) {
+			console.error(`Error loading config file at ${configPath}:`, e);
+		}
+	}
+	/**
+	* Utility to ensure directory exists
+	*
+	* @param filePath
+	*/
+	ensureDirectory(filePath) {
+		const dir = dirname(filePath);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	}
+	/**
+	* Utility to generate file from stub
+	*
+	* @param stubPath
+	* @param outputPath
+	* @param replacements
+	*/
+	generateFile(stubPath, outputPath, replacements, options) {
+		if (existsSync(outputPath) && !options?.force) {
+			this.command.error(`Error: ${outputPath} already exists.`);
+			process.exit(1);
+		} else if (existsSync(outputPath) && options?.force) rmSync(outputPath);
+		let content = readFileSync(stubPath, "utf-8");
+		for (const [key, value] of Object.entries(replacements)) content = content.replace(new RegExp(`{{${key}}}`, "g"), value);
+		this.ensureDirectory(outputPath);
+		writeFileSync(outputPath, content);
+		return outputPath;
+	}
+	/**
+	* Command to create a new resource or resource collection file
+	*
+	* @param name
+	* @param options
+	*/
+	makeResource(name, options) {
+		let resourceName = name;
+		if (options?.collection && !name.endsWith("Collection") && !name.endsWith("Resource")) resourceName += "Collection";
+		else if (!options?.collection && !name.endsWith("Resource") && !name.endsWith("Collection")) resourceName += "Resource";
+		const fileName = `${resourceName}.ts`;
+		const outputPath = join(this.config.resourcesDir, fileName);
+		const stubPath = join(this.config.stubsDir, options?.collection || name.endsWith("Collection") ? this.config.stubs.collection : this.config.stubs.resource);
+		if (!existsSync(stubPath)) {
+			this.command.error(`Error: Stub file ${stubPath} not found.`);
+			process.exit(1);
+		}
+		const collectsName = resourceName.replace(/(Resource|Collection)$/, "") + "Resource";
+		const collects = `/** 
+     * The resource that this collection collects.
+     */
+    collects = ${collectsName}
+    `;
+		const collectsImport = `import ${collectsName} from './${collectsName}'\n`;
+		const hasCollects = (!!options?.collection || name.endsWith("Collection")) && existsSync(join(this.config.resourcesDir, `${collectsName}.ts`));
+		const path = this.generateFile(stubPath, outputPath, {
+			ResourceName: resourceName,
+			CollectionResourceName: resourceName.replace(/(Resource|Collection)$/, "") + "Resource",
+			"collects = Resource": hasCollects ? collects : "",
+			"import = Resource": hasCollects ? collectsImport : ""
+		}, options);
+		return {
+			name: resourceName,
+			path
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/commands/MakeResource.ts
+var MakeResource = class extends Command {
+	signature = `#create:
+        {resource : Generates a new resource file.
+            | {name : Name of the resource to create}
+            | {--c|collection : Make a resource collection}
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+        {collection : Create a new resource collection file.
+            | {name : Name of the resource collection to create}
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+        {all : Create both resource and collection files.
+            | {prefix : prefix of the resources to create, "Admin" will create AdminResource, AdminCollection} 
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+    `;
+	description = "Create a new resource or resource collection file";
+	async handle() {
+		this.app.command = this;
+		let path = "";
+		const action = this.dictionary.name || this.dictionary.baseCommand;
+		if (["resource", "collection"].includes(action) && !this.argument("name")) return void this.error("Error: Name argument is required.");
+		if (action === "all" && !this.argument("prefix")) return void this.error("Error: Prefix argument is required.");
+		switch (action) {
+			case "resource":
+				({path} = this.app.makeResource(this.argument("name"), this.options()));
+				break;
+			case "collection":
+				({path} = this.app.makeResource(this.argument("name") + "Collection", this.options()));
+				break;
+			case "all": {
+				const o1 = this.app.makeResource(this.argument("prefix"), { force: this.option("force") });
+				const o2 = this.app.makeResource(this.argument("prefix") + "Collection", {
+					collection: true,
+					force: this.option("force")
+				});
+				path = `${o1.path}, ${o2.path}`;
+				break;
+			}
+			default: this.fail(`Unknown action: ${action}`);
+		}
+		this.success(`Created: ${path}`);
+	}
+};
+
+//#endregion
+//#region src/cli/logo.ts
+var logo_default = String.raw`
+  _____                           
+ |  __ \                          
+ | |__) |___  ___  ___  _ __ __ _ 
+ |  _  // _ \/ __|/ _ \| '__/ _, |
+ | | \ \  __/\__ \ (_) | | | (_| |
+ |_|  \_\___||___/\___/|_|  \__,_|                                                                                           
+`;
+
+//#endregion
+//#region src/cli/index.ts
+const app = new CliApp();
+await Kernel.init(app, {
+	logo: logo_default,
+	name: "Resora CLI",
+	baseCommands: [MakeResource],
+	exceptionHandler(exception) {
+		throw exception;
+	}
+});
+
+//#endregion
+export {  };

package/dist/index.cjs

@@ -1,4 +1,37 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let path = require("path");
+path = __toESM(path);
+let fs = require("fs");
+let module$1 = require("module");
+let url = require("url");
+let _h3ravel_musket = require("@h3ravel/musket");
 
 //#region src/ApiResource.ts
 /**
@@ -11,6 +44,175 @@ function ApiResource(instance) {
 	return instance;
 }
 
+//#endregion
+//#region src/utility.ts
+const __dirname$1 = /* @__PURE__ */ path.default.dirname((0, url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
+let stubsDir = path.default.resolve(__dirname$1, "../node_modules/resora/stubs");
+if (!(0, fs.existsSync)(stubsDir)) stubsDir = path.default.resolve(__dirname$1, "../stubs");
+/**
+* Define the configuration for the package
+* 
+* @param userConfig  The user configuration to override the default configuration
+* @returns The merged configuration object
+*/
+const defineConfig = (userConfig = {}) => {
+	return Object.assign({
+		resourcesDir: "src/resources",
+		stubsDir,
+		stubs: {
+			resource: "resource.stub",
+			collection: "resource.collection.stub"
+		}
+	}, userConfig, { stubs: Object.assign({
+		resource: "resource.stub",
+		collection: "resource.collection.stub"
+	}, userConfig.stubs || {}) });
+};
+
+//#endregion
+//#region src/cli/actions.ts
+var CliApp = class {
+	command;
+	config = {};
+	constructor(config = {}) {
+		this.config = defineConfig(config);
+		const require = (0, module$1.createRequire)(require("url").pathToFileURL(__filename).href);
+		const possibleConfigPaths = [
+			(0, path.join)(process.cwd(), "resora.config.ts"),
+			(0, path.join)(process.cwd(), "resora.config.js"),
+			(0, path.join)(process.cwd(), "resora.config.cjs")
+		];
+		for (const configPath of possibleConfigPaths) if ((0, fs.existsSync)(configPath)) try {
+			const { default: userConfig } = require(configPath);
+			Object.assign(this.config, defineConfig(userConfig));
+			break;
+		} catch (e) {
+			console.error(`Error loading config file at ${configPath}:`, e);
+		}
+	}
+	/**
+	* Utility to ensure directory exists
+	*
+	* @param filePath
+	*/
+	ensureDirectory(filePath) {
+		const dir = (0, path.dirname)(filePath);
+		if (!(0, fs.existsSync)(dir)) (0, fs.mkdirSync)(dir, { recursive: true });
+	}
+	/**
+	* Utility to generate file from stub
+	*
+	* @param stubPath
+	* @param outputPath
+	* @param replacements
+	*/
+	generateFile(stubPath, outputPath, replacements, options) {
+		if ((0, fs.existsSync)(outputPath) && !options?.force) {
+			this.command.error(`Error: ${outputPath} already exists.`);
+			process.exit(1);
+		} else if ((0, fs.existsSync)(outputPath) && options?.force) (0, fs.rmSync)(outputPath);
+		let content = (0, fs.readFileSync)(stubPath, "utf-8");
+		for (const [key, value] of Object.entries(replacements)) content = content.replace(new RegExp(`{{${key}}}`, "g"), value);
+		this.ensureDirectory(outputPath);
+		(0, fs.writeFileSync)(outputPath, content);
+		return outputPath;
+	}
+	/**
+	* Command to create a new resource or resource collection file
+	*
+	* @param name
+	* @param options
+	*/
+	makeResource(name, options) {
+		let resourceName = name;
+		if (options?.collection && !name.endsWith("Collection") && !name.endsWith("Resource")) resourceName += "Collection";
+		else if (!options?.collection && !name.endsWith("Resource") && !name.endsWith("Collection")) resourceName += "Resource";
+		const fileName = `${resourceName}.ts`;
+		const outputPath = (0, path.join)(this.config.resourcesDir, fileName);
+		const stubPath = (0, path.join)(this.config.stubsDir, options?.collection || name.endsWith("Collection") ? this.config.stubs.collection : this.config.stubs.resource);
+		if (!(0, fs.existsSync)(stubPath)) {
+			this.command.error(`Error: Stub file ${stubPath} not found.`);
+			process.exit(1);
+		}
+		const collectsName = resourceName.replace(/(Resource|Collection)$/, "") + "Resource";
+		const collects = `/** 
+     * The resource that this collection collects.
+     */
+    collects = ${collectsName}
+    `;
+		const collectsImport = `import ${collectsName} from './${collectsName}'\n`;
+		const hasCollects = (!!options?.collection || name.endsWith("Collection")) && (0, fs.existsSync)((0, path.join)(this.config.resourcesDir, `${collectsName}.ts`));
+		const path$2 = this.generateFile(stubPath, outputPath, {
+			ResourceName: resourceName,
+			CollectionResourceName: resourceName.replace(/(Resource|Collection)$/, "") + "Resource",
+			"collects = Resource": hasCollects ? collects : "",
+			"import = Resource": hasCollects ? collectsImport : ""
+		}, options);
+		return {
+			name: resourceName,
+			path: path$2
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/commands/MakeResource.ts
+var MakeResource = class extends _h3ravel_musket.Command {
+	signature = `#create:
+        {resource : Generates a new resource file.
+            | {name : Name of the resource to create}
+            | {--c|collection : Make a resource collection}
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+        {collection : Create a new resource collection file.
+            | {name : Name of the resource collection to create}
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+        {all : Create both resource and collection files.
+            | {prefix : prefix of the resources to create, "Admin" will create AdminResource, AdminCollection} 
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+    `;
+	description = "Create a new resource or resource collection file";
+	async handle() {
+		this.app.command = this;
+		let path = "";
+		const action = this.dictionary.name || this.dictionary.baseCommand;
+		if (["resource", "collection"].includes(action) && !this.argument("name")) return void this.error("Error: Name argument is required.");
+		if (action === "all" && !this.argument("prefix")) return void this.error("Error: Prefix argument is required.");
+		switch (action) {
+			case "resource":
+				({path} = this.app.makeResource(this.argument("name"), this.options()));
+				break;
+			case "collection":
+				({path} = this.app.makeResource(this.argument("name") + "Collection", this.options()));
+				break;
+			case "all": {
+				const o1 = this.app.makeResource(this.argument("prefix"), { force: this.option("force") });
+				const o2 = this.app.makeResource(this.argument("prefix") + "Collection", {
+					collection: true,
+					force: this.option("force")
+				});
+				path = `${o1.path}, ${o2.path}`;
+				break;
+			}
+			default: this.fail(`Unknown action: ${action}`);
+		}
+		this.success(`Created: ${path}`);
+	}
+};
+
+//#endregion
+//#region src/cli/logo.ts
+var logo_default = String.raw`
+  _____                           
+ |  __ \                          
+ | |__) |___  ___  ___  _ __ __ _ 
+ |  _  // _ \/ __|/ _ \| '__/ _, |
+ | | \ \  __/\__ \ (_) | | | (_| |
+ |_|  \_\___||___/\___/|_|  \__,_|                                                                                           
+`;
+
 //#endregion
 //#region src/ServerResponse.ts
 var ServerResponse = class {
@@ -125,6 +327,113 @@ var ServerResponse = class {
 	}
 };
 
+//#endregion
+//#region src/GenericResource.ts
+/**
+* GenericResource class to handle API resource transformation and response building
+*/
+var GenericResource = class {
+	body = { data: {} };
+	resource;
+	collects;
+	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;
+				}
+			});
+		}
+	}
+	/**
+	* Get the original resource data
+	*/
+	data() {
+		return this.resource;
+	}
+	/**
+	* 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 (Array.isArray(data) && this.collects) {
+				data = data.map((item) => new this.collects(item).data());
+				this.resource = data;
+			}
+			if (typeof data.data !== "undefined") data = data.data;
+			if (this.resource.pagination && data.data && Array.isArray(data.data)) delete data.pagination;
+			this.body = { data };
+			if (Array.isArray(this.body.data) && this.resource.pagination) this.body.meta = { pagination: this.resource.pagination };
+		}
+		return this;
+	}
+	/**
+	* Convert resource to array format (for collections)
+	*
+	* @returns
+	*/
+	toArray() {
+		this.called.toArray = true;
+		this.json();
+		let data = Array.isArray(this.resource) ? [...this.resource] : { ...this.resource };
+		if (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();
+		delete extra.data;
+		delete extra.pagination;
+		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;
+	}
+};
+
 //#endregion
 //#region src/ResourceCollection.ts
 /**
@@ -368,4 +677,10 @@ var Resource = class {
 
 //#endregion
 exports.ApiResource = ApiResource;
-exports.Resource = Resource;
+exports.CliApp = CliApp;
+exports.GenericResource = GenericResource;
+exports.MakeResource = MakeResource;
+exports.Resource = Resource;
+exports.ResourceCollection = ResourceCollection;
+exports.ServerResponse = ServerResponse;
+exports.defineConfig = defineConfig;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { Command } from "@h3ravel/musket";
 import { H3Event } from "h3";
 import { Response } from "express";
 
@@ -17,7 +18,7 @@ interface MetaData {
 interface ResourceData {
   [key: string]: any;
 }
-interface Resource$1 extends ResourceData {
+interface ResourceDef extends ResourceData {
   cursor?: Cursor | undefined;
   pagination?: Pagination | undefined;
 }
@@ -29,11 +30,38 @@ interface Collectible {
   cursor?: Cursor | undefined;
   pagination?: Pagination | undefined;
 }
-interface ResponseData<R extends ResourceData = any> extends Resource$1 {
+interface ResponseData<R extends ResourceData = any> extends ResourceDef {
   data: R;
   meta?: MetaData | undefined;
 }
+/**
+ * @description A type that represents the metadata for a paginated collection of resources. It extends the MetaData type and includes all properties of a Collectible object except for the data property. This type is used to provide additional information about the paginated collection, such as pagination details, without including the actual resource data.
+ * @example
+ * const paginatedMeta: PaginatedMetaData = {
+ *   pagination: {
+ *     currentPage: 1,
+ *     total: 100
+ *   },
+ *   timestamp: '2024-06-01T12:00:00Z'
+ * };
+ */
 type PaginatedMetaData<R extends Collectible = Collectible> = MetaData & Omit<R, 'data'>;
+/**
+ * @description A type that represents the body of a response for a collection of resources. It includes a data property, which can be either an array of ResourceData objects or a Collectible object, and an optional meta property that can contain any additional metadata related to the response. The type is generic and can be used to define the structure of the response body for API endpoints that return collections of resources.
+ * @example
+ * const collectionResponse: CollectionBody = {
+ *   data: [
+ *     { id: 1, name: 'Resource 1' },
+ *     { id: 2, name: 'Resource 2' }
+ *   ],
+ *   meta: {
+ *     pagination: {
+ *       currentPage: 1,
+ *       total: 2
+ *     }
+ *   }
+ * };
+ */
 interface ResponseDataCollection<R extends Collectible | undefined = undefined> extends ResourceData {
   data: R extends Collectible ? R['data'] : R;
   meta?: R extends Collectible ? PaginatedMetaData<R> | undefined : undefined;
@@ -80,6 +108,23 @@ type CollectionBody<R extends ResourceData[] | Collectible = ResourceData[]> = R
 type ResourceBody<R extends ResourceData | NonCollectible = ResourceData> = ResponseData<R extends NonCollectible ? R : {
   data: R;
 }>;
+/**
+ * @description A type that represents the body of a response for either a single resource or a collection of resources.
+ * It can be either a ResourceData object, an array of ResourceData objects, a NonCollectible object, or a Collectible object.
+ * The type also includes the meta property, which is optional and can contain any additional metadata related to the response.
+ * @example
+ * const genericResponse: GenericBody = {
+ *   data: {
+ *     id: 1,
+ *     name: 'Resource Name',
+ *     description: 'Resource Description'
+ *   },
+ *   meta: {
+ *     timestamp: '2024-06-01T12:00:00Z'
+ *   }
+ * };
+ */
+type GenericBody<R extends NonCollectible | Collectible | ResourceData = ResourceData> = ResponseData<R>;
 /**
  * @description A type that represents the pagination information for a collection of resources. It includes properties such as currentPage, from, to, perPage, total, firstPage, lastPage, prevPage, and nextPage. All properties are optional and can be undefined if not applicable.
  * @example
@@ -118,6 +163,67 @@ interface Cursor {
   previous?: string | undefined;
   next?: string | undefined;
 }
+interface Config {
+  /**
+   * @description The directory where resource files are stored. This is the location where the generated resource files will be saved. It should be a valid path on the file system.
+   */
+  resourcesDir: string;
+  /**
+   * @description The directory where stub files are stored. Stub files are templates used for generating resource files. This should also be a valid path on the file system where the stub templates are located.
+   */
+  stubsDir: string;
+  /**
+   * @description An object that defines the stub file names for different types of resources.
+   */
+  stubs: {
+    /**
+     * @description The stub file name for a resource. This stub will be used when generating a resource file.
+     */
+    resource: string;
+    /**
+     * @description The stub file name for a collection resource. This stub will be used when generating a collection resource file.
+     */
+    collection: string;
+  };
+}
+//#endregion
+//#region src/cli/actions.d.ts
+declare class CliApp {
+  command: Command;
+  private config;
+  constructor(config?: Partial<Config>);
+  /**
+   * Utility to ensure directory exists
+   *
+   * @param filePath
+   */
+  ensureDirectory(filePath: string): void;
+  /**
+   * Utility to generate file from stub
+   *
+   * @param stubPath
+   * @param outputPath
+   * @param replacements
+   */
+  generateFile(stubPath: string, outputPath: string, replacements: Record<string, string>, options?: any): string;
+  /**
+   * Command to create a new resource or resource collection file
+   *
+   * @param name
+   * @param options
+   */
+  makeResource(name: string, options: any): {
+    name: string;
+    path: string;
+  };
+}
+//#endregion
+//#region src/cli/commands/MakeResource.d.ts
+declare class MakeResource extends Command<CliApp> {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<undefined>;
+}
 //#endregion
 //#region src/ServerResponse.d.ts
 declare class ServerResponse<R extends NonCollectible | Collectible | ResourceData[] | ResourceData = ResourceData> {
@@ -325,4 +431,62 @@ declare class Resource<R extends ResourceData | NonCollectible = ResourceData> {
   finally(onfinally?: (() => void) | null): Promise<void>;
 }
 //#endregion
-export { ApiResource, Resource };
+//#region src/GenericResource.d.ts
+/**
+ * GenericResource class to handle API resource transformation and response building
+ */
+declare class GenericResource<R extends NonCollectible | Collectible | ResourceData = ResourceData, T extends ResourceData = any> {
+  private res?;
+  [key: string]: any;
+  body: GenericBody<R>;
+  resource: R;
+  collects?: typeof Resource<T>;
+  private called;
+  constructor(rsc: R, res?: Response | undefined);
+  /**
+   * Get the original resource data
+   */
+  data(): R;
+  /**
+   * Convert resource to JSON response format
+   *
+   * @returns
+   */
+  json(): this;
+  /**
+   * Convert resource to array format (for collections)
+   *
+   * @returns
+   */
+  toArray(): any;
+  /**
+   * Add additional properties to the response body
+   *
+   * @param extra  Additional properties to merge into the response body
+   * @returns
+   */
+  additional<X extends Record<string, any>>(extra: X): this;
+  response(): ServerResponse<GenericBody<R>>;
+  response(res: H3Event['res']): ServerResponse<GenericBody<R>>;
+  /**
+   * 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<TResult1 = GenericBody<R>, TResult2 = never>(onfulfilled?: ((value: GenericBody<R>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+//#endregion
+//#region src/utility.d.ts
+/**
+ * Define the configuration for the package
+ *
+ * @param userConfig  The user configuration to override the default configuration
+ * @returns The merged configuration object
+ */
+declare const defineConfig: (userConfig?: Partial<Omit<Config, "stubs">> & {
+  stubs?: Partial<Config["stubs"]>;
+}) => Config;
+//#endregion
+export { ApiResource, CliApp, Collectible, CollectionBody, Config, Cursor, GenericBody, GenericResource, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResponseData, ResponseDataCollection, ServerResponse, defineConfig };

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { Command } from "@h3ravel/musket";
 import { H3Event } from "h3";
 import { Response } from "express";
 
@@ -17,7 +18,7 @@ interface MetaData {
 interface ResourceData {
   [key: string]: any;
 }
-interface Resource$1 extends ResourceData {
+interface ResourceDef extends ResourceData {
   cursor?: Cursor | undefined;
   pagination?: Pagination | undefined;
 }
@@ -29,11 +30,38 @@ interface Collectible {
   cursor?: Cursor | undefined;
   pagination?: Pagination | undefined;
 }
-interface ResponseData<R extends ResourceData = any> extends Resource$1 {
+interface ResponseData<R extends ResourceData = any> extends ResourceDef {
   data: R;
   meta?: MetaData | undefined;
 }
+/**
+ * @description A type that represents the metadata for a paginated collection of resources. It extends the MetaData type and includes all properties of a Collectible object except for the data property. This type is used to provide additional information about the paginated collection, such as pagination details, without including the actual resource data.
+ * @example
+ * const paginatedMeta: PaginatedMetaData = {
+ *   pagination: {
+ *     currentPage: 1,
+ *     total: 100
+ *   },
+ *   timestamp: '2024-06-01T12:00:00Z'
+ * };
+ */
 type PaginatedMetaData<R extends Collectible = Collectible> = MetaData & Omit<R, 'data'>;
+/**
+ * @description A type that represents the body of a response for a collection of resources. It includes a data property, which can be either an array of ResourceData objects or a Collectible object, and an optional meta property that can contain any additional metadata related to the response. The type is generic and can be used to define the structure of the response body for API endpoints that return collections of resources.
+ * @example
+ * const collectionResponse: CollectionBody = {
+ *   data: [
+ *     { id: 1, name: 'Resource 1' },
+ *     { id: 2, name: 'Resource 2' }
+ *   ],
+ *   meta: {
+ *     pagination: {
+ *       currentPage: 1,
+ *       total: 2
+ *     }
+ *   }
+ * };
+ */
 interface ResponseDataCollection<R extends Collectible | undefined = undefined> extends ResourceData {
   data: R extends Collectible ? R['data'] : R;
   meta?: R extends Collectible ? PaginatedMetaData<R> | undefined : undefined;
@@ -80,6 +108,23 @@ type CollectionBody<R extends ResourceData[] | Collectible = ResourceData[]> = R
 type ResourceBody<R extends ResourceData | NonCollectible = ResourceData> = ResponseData<R extends NonCollectible ? R : {
   data: R;
 }>;
+/**
+ * @description A type that represents the body of a response for either a single resource or a collection of resources.
+ * It can be either a ResourceData object, an array of ResourceData objects, a NonCollectible object, or a Collectible object.
+ * The type also includes the meta property, which is optional and can contain any additional metadata related to the response.
+ * @example
+ * const genericResponse: GenericBody = {
+ *   data: {
+ *     id: 1,
+ *     name: 'Resource Name',
+ *     description: 'Resource Description'
+ *   },
+ *   meta: {
+ *     timestamp: '2024-06-01T12:00:00Z'
+ *   }
+ * };
+ */
+type GenericBody<R extends NonCollectible | Collectible | ResourceData = ResourceData> = ResponseData<R>;
 /**
  * @description A type that represents the pagination information for a collection of resources. It includes properties such as currentPage, from, to, perPage, total, firstPage, lastPage, prevPage, and nextPage. All properties are optional and can be undefined if not applicable.
  * @example
@@ -118,6 +163,67 @@ interface Cursor {
   previous?: string | undefined;
   next?: string | undefined;
 }
+interface Config {
+  /**
+   * @description The directory where resource files are stored. This is the location where the generated resource files will be saved. It should be a valid path on the file system.
+   */
+  resourcesDir: string;
+  /**
+   * @description The directory where stub files are stored. Stub files are templates used for generating resource files. This should also be a valid path on the file system where the stub templates are located.
+   */
+  stubsDir: string;
+  /**
+   * @description An object that defines the stub file names for different types of resources.
+   */
+  stubs: {
+    /**
+     * @description The stub file name for a resource. This stub will be used when generating a resource file.
+     */
+    resource: string;
+    /**
+     * @description The stub file name for a collection resource. This stub will be used when generating a collection resource file.
+     */
+    collection: string;
+  };
+}
+//#endregion
+//#region src/cli/actions.d.ts
+declare class CliApp {
+  command: Command;
+  private config;
+  constructor(config?: Partial<Config>);
+  /**
+   * Utility to ensure directory exists
+   *
+   * @param filePath
+   */
+  ensureDirectory(filePath: string): void;
+  /**
+   * Utility to generate file from stub
+   *
+   * @param stubPath
+   * @param outputPath
+   * @param replacements
+   */
+  generateFile(stubPath: string, outputPath: string, replacements: Record<string, string>, options?: any): string;
+  /**
+   * Command to create a new resource or resource collection file
+   *
+   * @param name
+   * @param options
+   */
+  makeResource(name: string, options: any): {
+    name: string;
+    path: string;
+  };
+}
+//#endregion
+//#region src/cli/commands/MakeResource.d.ts
+declare class MakeResource extends Command<CliApp> {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<undefined>;
+}
 //#endregion
 //#region src/ServerResponse.d.ts
 declare class ServerResponse<R extends NonCollectible | Collectible | ResourceData[] | ResourceData = ResourceData> {
@@ -325,4 +431,62 @@ declare class Resource<R extends ResourceData | NonCollectible = ResourceData> {
   finally(onfinally?: (() => void) | null): Promise<void>;
 }
 //#endregion
-export { ApiResource, Resource };
+//#region src/GenericResource.d.ts
+/**
+ * GenericResource class to handle API resource transformation and response building
+ */
+declare class GenericResource<R extends NonCollectible | Collectible | ResourceData = ResourceData, T extends ResourceData = any> {
+  private res?;
+  [key: string]: any;
+  body: GenericBody<R>;
+  resource: R;
+  collects?: typeof Resource<T>;
+  private called;
+  constructor(rsc: R, res?: Response | undefined);
+  /**
+   * Get the original resource data
+   */
+  data(): R;
+  /**
+   * Convert resource to JSON response format
+   *
+   * @returns
+   */
+  json(): this;
+  /**
+   * Convert resource to array format (for collections)
+   *
+   * @returns
+   */
+  toArray(): any;
+  /**
+   * Add additional properties to the response body
+   *
+   * @param extra  Additional properties to merge into the response body
+   * @returns
+   */
+  additional<X extends Record<string, any>>(extra: X): this;
+  response(): ServerResponse<GenericBody<R>>;
+  response(res: H3Event['res']): ServerResponse<GenericBody<R>>;
+  /**
+   * 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<TResult1 = GenericBody<R>, TResult2 = never>(onfulfilled?: ((value: GenericBody<R>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+//#endregion
+//#region src/utility.d.ts
+/**
+ * Define the configuration for the package
+ *
+ * @param userConfig  The user configuration to override the default configuration
+ * @returns The merged configuration object
+ */
+declare const defineConfig: (userConfig?: Partial<Omit<Config, "stubs">> & {
+  stubs?: Partial<Config["stubs"]>;
+}) => Config;
+//#endregion
+export { ApiResource, CliApp, Collectible, CollectionBody, Config, Cursor, GenericBody, GenericResource, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResponseData, ResponseDataCollection, ServerResponse, defineConfig };

package/dist/index.mjs

@@ -1,3 +1,9 @@
+import path, { dirname, join } from "path";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { Command } from "@h3ravel/musket";
+
 //#region src/ApiResource.ts
 /**
 * ApiResource function to return the Resource instance
@@ -9,6 +15,175 @@ function ApiResource(instance) {
 	return instance;
 }
 
+//#endregion
+//#region src/utility.ts
+const __dirname = /* @__PURE__ */ path.dirname(fileURLToPath(import.meta.url));
+let stubsDir = path.resolve(__dirname, "../node_modules/resora/stubs");
+if (!existsSync(stubsDir)) stubsDir = path.resolve(__dirname, "../stubs");
+/**
+* Define the configuration for the package
+* 
+* @param userConfig  The user configuration to override the default configuration
+* @returns The merged configuration object
+*/
+const defineConfig = (userConfig = {}) => {
+	return Object.assign({
+		resourcesDir: "src/resources",
+		stubsDir,
+		stubs: {
+			resource: "resource.stub",
+			collection: "resource.collection.stub"
+		}
+	}, userConfig, { stubs: Object.assign({
+		resource: "resource.stub",
+		collection: "resource.collection.stub"
+	}, userConfig.stubs || {}) });
+};
+
+//#endregion
+//#region src/cli/actions.ts
+var CliApp = class {
+	command;
+	config = {};
+	constructor(config = {}) {
+		this.config = defineConfig(config);
+		const require = createRequire(import.meta.url);
+		const possibleConfigPaths = [
+			join(process.cwd(), "resora.config.ts"),
+			join(process.cwd(), "resora.config.js"),
+			join(process.cwd(), "resora.config.cjs")
+		];
+		for (const configPath of possibleConfigPaths) if (existsSync(configPath)) try {
+			const { default: userConfig } = require(configPath);
+			Object.assign(this.config, defineConfig(userConfig));
+			break;
+		} catch (e) {
+			console.error(`Error loading config file at ${configPath}:`, e);
+		}
+	}
+	/**
+	* Utility to ensure directory exists
+	*
+	* @param filePath
+	*/
+	ensureDirectory(filePath) {
+		const dir = dirname(filePath);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	}
+	/**
+	* Utility to generate file from stub
+	*
+	* @param stubPath
+	* @param outputPath
+	* @param replacements
+	*/
+	generateFile(stubPath, outputPath, replacements, options) {
+		if (existsSync(outputPath) && !options?.force) {
+			this.command.error(`Error: ${outputPath} already exists.`);
+			process.exit(1);
+		} else if (existsSync(outputPath) && options?.force) rmSync(outputPath);
+		let content = readFileSync(stubPath, "utf-8");
+		for (const [key, value] of Object.entries(replacements)) content = content.replace(new RegExp(`{{${key}}}`, "g"), value);
+		this.ensureDirectory(outputPath);
+		writeFileSync(outputPath, content);
+		return outputPath;
+	}
+	/**
+	* Command to create a new resource or resource collection file
+	*
+	* @param name
+	* @param options
+	*/
+	makeResource(name, options) {
+		let resourceName = name;
+		if (options?.collection && !name.endsWith("Collection") && !name.endsWith("Resource")) resourceName += "Collection";
+		else if (!options?.collection && !name.endsWith("Resource") && !name.endsWith("Collection")) resourceName += "Resource";
+		const fileName = `${resourceName}.ts`;
+		const outputPath = join(this.config.resourcesDir, fileName);
+		const stubPath = join(this.config.stubsDir, options?.collection || name.endsWith("Collection") ? this.config.stubs.collection : this.config.stubs.resource);
+		if (!existsSync(stubPath)) {
+			this.command.error(`Error: Stub file ${stubPath} not found.`);
+			process.exit(1);
+		}
+		const collectsName = resourceName.replace(/(Resource|Collection)$/, "") + "Resource";
+		const collects = `/** 
+     * The resource that this collection collects.
+     */
+    collects = ${collectsName}
+    `;
+		const collectsImport = `import ${collectsName} from './${collectsName}'\n`;
+		const hasCollects = (!!options?.collection || name.endsWith("Collection")) && existsSync(join(this.config.resourcesDir, `${collectsName}.ts`));
+		const path = this.generateFile(stubPath, outputPath, {
+			ResourceName: resourceName,
+			CollectionResourceName: resourceName.replace(/(Resource|Collection)$/, "") + "Resource",
+			"collects = Resource": hasCollects ? collects : "",
+			"import = Resource": hasCollects ? collectsImport : ""
+		}, options);
+		return {
+			name: resourceName,
+			path
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/commands/MakeResource.ts
+var MakeResource = class extends Command {
+	signature = `#create:
+        {resource : Generates a new resource file.
+            | {name : Name of the resource to create}
+            | {--c|collection : Make a resource collection}
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+        {collection : Create a new resource collection file.
+            | {name : Name of the resource collection to create}
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+        {all : Create both resource and collection files.
+            | {prefix : prefix of the resources to create, "Admin" will create AdminResource, AdminCollection} 
+            | {--force : Create the resource or collection file even if it already exists.}
+        }
+    `;
+	description = "Create a new resource or resource collection file";
+	async handle() {
+		this.app.command = this;
+		let path = "";
+		const action = this.dictionary.name || this.dictionary.baseCommand;
+		if (["resource", "collection"].includes(action) && !this.argument("name")) return void this.error("Error: Name argument is required.");
+		if (action === "all" && !this.argument("prefix")) return void this.error("Error: Prefix argument is required.");
+		switch (action) {
+			case "resource":
+				({path} = this.app.makeResource(this.argument("name"), this.options()));
+				break;
+			case "collection":
+				({path} = this.app.makeResource(this.argument("name") + "Collection", this.options()));
+				break;
+			case "all": {
+				const o1 = this.app.makeResource(this.argument("prefix"), { force: this.option("force") });
+				const o2 = this.app.makeResource(this.argument("prefix") + "Collection", {
+					collection: true,
+					force: this.option("force")
+				});
+				path = `${o1.path}, ${o2.path}`;
+				break;
+			}
+			default: this.fail(`Unknown action: ${action}`);
+		}
+		this.success(`Created: ${path}`);
+	}
+};
+
+//#endregion
+//#region src/cli/logo.ts
+var logo_default = String.raw`
+  _____                           
+ |  __ \                          
+ | |__) |___  ___  ___  _ __ __ _ 
+ |  _  // _ \/ __|/ _ \| '__/ _, |
+ | | \ \  __/\__ \ (_) | | | (_| |
+ |_|  \_\___||___/\___/|_|  \__,_|                                                                                           
+`;
+
 //#endregion
 //#region src/ServerResponse.ts
 var ServerResponse = class {
@@ -123,6 +298,113 @@ var ServerResponse = class {
 	}
 };
 
+//#endregion
+//#region src/GenericResource.ts
+/**
+* GenericResource class to handle API resource transformation and response building
+*/
+var GenericResource = class {
+	body = { data: {} };
+	resource;
+	collects;
+	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;
+				}
+			});
+		}
+	}
+	/**
+	* Get the original resource data
+	*/
+	data() {
+		return this.resource;
+	}
+	/**
+	* 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 (Array.isArray(data) && this.collects) {
+				data = data.map((item) => new this.collects(item).data());
+				this.resource = data;
+			}
+			if (typeof data.data !== "undefined") data = data.data;
+			if (this.resource.pagination && data.data && Array.isArray(data.data)) delete data.pagination;
+			this.body = { data };
+			if (Array.isArray(this.body.data) && this.resource.pagination) this.body.meta = { pagination: this.resource.pagination };
+		}
+		return this;
+	}
+	/**
+	* Convert resource to array format (for collections)
+	*
+	* @returns
+	*/
+	toArray() {
+		this.called.toArray = true;
+		this.json();
+		let data = Array.isArray(this.resource) ? [...this.resource] : { ...this.resource };
+		if (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();
+		delete extra.data;
+		delete extra.pagination;
+		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;
+	}
+};
+
 //#endregion
 //#region src/ResourceCollection.ts
 /**
@@ -365,4 +647,4 @@ var Resource = class {
 };
 
 //#endregion
-export { ApiResource, Resource };
+export { ApiResource, CliApp, GenericResource, MakeResource, Resource, ResourceCollection, ServerResponse, defineConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resora",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A structured API response layer for Node.js and TypeScript with automatic JSON responses, collection support, and pagination handling.",
   "keywords": [
     "api",
@@ -37,9 +37,14 @@
   },
   "files": [
     "dist",
+    "stubs",
+    "bin",
     "README.md",
     "LICENSE"
   ],
+  "bin": {
+    "resora": "bin/index.mjs"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@eslint/markdown": "^7.5.1",
@@ -64,7 +69,11 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "dependencies": {
+    "@h3ravel/musket": "^0.10.1"
+  },
   "scripts": {
+    "cmd": "tsx src/cli/index.ts",
     "lint": "eslint",
     "test": "pnpm vitest",
     "test:coverage": "pnpm vitest --coverage --watch=false",

package/stubs/resource.collection.stub

@@ -0,0 +1,16 @@
+import { ResourceCollection } from 'resora'
+{{import = Resource}}
+/**
+ * {{ResourceName}}
+ */
+export default class {{ResourceName}} extends ResourceCollection {
+    {{collects = Resource}}
+    /**
+     * Transform the resource into a plain JavaScript object.
+     *
+     * @memberof {{ResourceName}}
+     */
+    data () {
+        return this.toArray()
+    }
+}

package/stubs/resource.stub

@@ -0,0 +1,15 @@
+import { Resource } from 'resora'
+
+/**
+ * {{ResourceName}}
+ */
+export default class {{ResourceName}} extends Resource {
+    /**
+     * Transform the resource into a plain JavaScript object.
+     *
+     * @memberof {{ResourceName}}
+     */
+    data () {
+        return this.toArray()
+    }
+}