resora 0.1.11 → 0.2.1

package/dist/index.mjs

@@ -14,14 +14,347 @@ function ApiResource(instance) {
 }
 
 //#endregion
-//#region src/utility.ts
+//#region src/utilities/state.ts
+let globalPreferredCase;
+let globalResponseStructure;
+let globalPaginatedExtras = ["meta", "links"];
+let globalPaginatedLinks = {
+	first: "first",
+	last: "last",
+	prev: "prev",
+	next: "next"
+};
+let globalBaseUrl = "https://localhost";
+let globalPageName = "page";
+let globalPaginatedMeta = {
+	to: "to",
+	from: "from",
+	links: "links",
+	path: "path",
+	total: "total",
+	per_page: "per_page",
+	last_page: "last_page",
+	current_page: "current_page"
+};
+let globalCursorMeta = {
+	previous: "previous",
+	next: "next"
+};
+const setGlobalCase = (style) => {
+	globalPreferredCase = style;
+};
+const getGlobalCase = () => {
+	return globalPreferredCase;
+};
+const setGlobalResponseStructure = (config) => {
+	globalResponseStructure = config;
+};
+const getGlobalResponseStructure = () => {
+	return globalResponseStructure;
+};
+const setGlobalResponseRootKey = (rootKey) => {
+	globalResponseStructure = {
+		...globalResponseStructure || {},
+		rootKey
+	};
+};
+const setGlobalResponseWrap = (wrap) => {
+	globalResponseStructure = {
+		...globalResponseStructure || {},
+		wrap
+	};
+};
+const getGlobalResponseWrap = () => {
+	return globalResponseStructure?.wrap;
+};
+const getGlobalResponseRootKey = () => {
+	return globalResponseStructure?.rootKey;
+};
+const setGlobalResponseFactory = (factory) => {
+	globalResponseStructure = {
+		...globalResponseStructure || {},
+		factory
+	};
+};
+const getGlobalResponseFactory = () => {
+	return globalResponseStructure?.factory;
+};
+const setGlobalPaginatedExtras = (extras) => {
+	globalPaginatedExtras = extras;
+};
+const getGlobalPaginatedExtras = () => {
+	return globalPaginatedExtras;
+};
+const setGlobalPaginatedLinks = (links) => {
+	globalPaginatedLinks = {
+		...globalPaginatedLinks,
+		...links
+	};
+};
+const getGlobalPaginatedLinks = () => {
+	return globalPaginatedLinks;
+};
+const setGlobalBaseUrl = (baseUrl) => {
+	globalBaseUrl = baseUrl;
+};
+const getGlobalBaseUrl = () => {
+	return globalBaseUrl;
+};
+const setGlobalPageName = (pageName) => {
+	globalPageName = pageName;
+};
+const getGlobalPageName = () => {
+	return globalPageName;
+};
+const setGlobalPaginatedMeta = (meta) => {
+	globalPaginatedMeta = {
+		...globalPaginatedMeta,
+		...meta
+	};
+};
+const getGlobalPaginatedMeta = () => {
+	return globalPaginatedMeta;
+};
+const setGlobalCursorMeta = (meta) => {
+	globalCursorMeta = {
+		...globalCursorMeta,
+		...meta
+	};
+};
+const getGlobalCursorMeta = () => {
+	return globalCursorMeta;
+};
+
+//#endregion
+//#region src/utilities/pagination.ts
+const getPaginationExtraKeys = () => {
+	const extras = getGlobalPaginatedExtras();
+	if (Array.isArray(extras)) return {
+		metaKey: extras.includes("meta") ? "meta" : void 0,
+		linksKey: extras.includes("links") ? "links" : void 0,
+		cursorKey: extras.includes("cursor") ? "cursor" : void 0
+	};
+	return {
+		metaKey: extras.meta,
+		linksKey: extras.links,
+		cursorKey: extras.cursor
+	};
+};
+const buildPageUrl = (page, pathName) => {
+	if (typeof page === "undefined") return;
+	const rawPath = pathName || "";
+	const base = getGlobalBaseUrl() || "";
+	const isAbsolutePath = /^https?:\/\//i.test(rawPath);
+	const normalizedBase = base.replace(/\/$/, "");
+	const normalizedPath = rawPath.replace(/^\//, "");
+	const root = isAbsolutePath ? rawPath : normalizedBase ? normalizedPath ? `${normalizedBase}/${normalizedPath}` : normalizedBase : "";
+	if (!root) return;
+	const url = new URL(root);
+	url.searchParams.set(getGlobalPageName() || "page", String(page));
+	return url.toString();
+};
+const buildPaginationExtras = (resource) => {
+	const { metaKey, linksKey, cursorKey } = getPaginationExtraKeys();
+	const extra = {};
+	const pagination = resource?.pagination;
+	const cursor = resource?.cursor;
+	const metaBlock = {};
+	const linksBlock = {};
+	if (pagination) {
+		const metaSource = {
+			to: pagination.to,
+			from: pagination.from,
+			links: pagination.links,
+			path: pagination.path,
+			total: pagination.total,
+			per_page: pagination.perPage,
+			last_page: pagination.lastPage,
+			current_page: pagination.currentPage
+		};
+		for (const [sourceKey, outputKey] of Object.entries(getGlobalPaginatedMeta())) {
+			if (!outputKey) continue;
+			const value = metaSource[sourceKey];
+			if (typeof value !== "undefined") metaBlock[outputKey] = value;
+		}
+		const linksSource = {
+			first: buildPageUrl(pagination.firstPage, pagination.path),
+			last: buildPageUrl(pagination.lastPage, pagination.path),
+			prev: buildPageUrl(pagination.prevPage, pagination.path),
+			next: buildPageUrl(pagination.nextPage, pagination.path)
+		};
+		for (const [sourceKey, outputKey] of Object.entries(getGlobalPaginatedLinks())) {
+			if (!outputKey) continue;
+			const value = linksSource[sourceKey];
+			if (typeof value !== "undefined") linksBlock[outputKey] = value;
+		}
+	}
+	if (cursor) {
+		const cursorBlock = {};
+		const cursorSource = {
+			previous: cursor.previous,
+			next: cursor.next
+		};
+		for (const [sourceKey, outputKey] of Object.entries(getGlobalCursorMeta())) {
+			if (!outputKey) continue;
+			const value = cursorSource[sourceKey];
+			if (typeof value !== "undefined") cursorBlock[outputKey] = value;
+		}
+		if (cursorKey && Object.keys(cursorBlock).length > 0) extra[cursorKey] = cursorBlock;
+		else if (Object.keys(cursorBlock).length > 0) metaBlock.cursor = cursorBlock;
+	}
+	if (metaKey && Object.keys(metaBlock).length > 0) extra[metaKey] = metaBlock;
+	if (linksKey && Object.keys(linksBlock).length > 0) extra[linksKey] = linksBlock;
+	return extra;
+};
+
+//#endregion
+//#region src/utilities/objects.ts
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	if (Array.isArray(value) || value instanceof Date || value instanceof RegExp) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+};
+const appendRootProperties = (body, extra, rootKey = "data") => {
+	if (!extra || Object.keys(extra).length === 0) return body;
+	if (Array.isArray(body)) return {
+		[rootKey]: body,
+		...extra
+	};
+	if (isPlainObject(body)) return {
+		...body,
+		...extra
+	};
+	return {
+		[rootKey]: body,
+		...extra
+	};
+};
+const mergeMetadata = (base, incoming) => {
+	if (!incoming) return base;
+	if (!base) return incoming;
+	const merged = { ...base };
+	for (const [key, value] of Object.entries(incoming)) {
+		const existing = merged[key];
+		if (isPlainObject(existing) && isPlainObject(value)) merged[key] = mergeMetadata(existing, value);
+		else merged[key] = value;
+	}
+	return merged;
+};
+
+//#endregion
+//#region src/utilities/response.ts
+const buildResponseEnvelope = ({ payload, meta, metaKey = "meta", wrap = true, rootKey = "data", factory, context }) => {
+	if (factory) return factory(payload, {
+		...context,
+		rootKey,
+		meta
+	});
+	if (!wrap) {
+		if (typeof meta === "undefined") return payload;
+		if (isPlainObject(payload)) return {
+			...payload,
+			[metaKey]: meta
+		};
+		return {
+			[rootKey]: payload,
+			[metaKey]: meta
+		};
+	}
+	const body = { [rootKey]: payload };
+	if (typeof meta !== "undefined") body[metaKey] = meta;
+	return body;
+};
+
+//#endregion
+//#region src/utilities/metadata.ts
+const resolveWithHookMetadata = (instance, baseWithMethod) => {
+	const candidate = instance?.with;
+	if (typeof candidate !== "function" || candidate === baseWithMethod) return;
+	if (candidate.length > 0) return;
+	const result = candidate.call(instance);
+	return isPlainObject(result) ? result : void 0;
+};
+
+//#endregion
+//#region src/utilities/conditional.ts
+const CONDITIONAL_ATTRIBUTE_MISSING = Symbol("resora.conditional.missing");
+const resolveWhen = (condition, value) => {
+	if (!condition) return CONDITIONAL_ATTRIBUTE_MISSING;
+	return typeof value === "function" ? value() : value;
+};
+const resolveWhenNotNull = (value) => {
+	return value === null || typeof value === "undefined" ? CONDITIONAL_ATTRIBUTE_MISSING : value;
+};
+const resolveMergeWhen = (condition, value) => {
+	if (!condition) return {};
+	const resolved = typeof value === "function" ? value() : value;
+	return isPlainObject(resolved) ? resolved : {};
+};
+const sanitizeConditionalAttributes = (value) => {
+	if (value === CONDITIONAL_ATTRIBUTE_MISSING) return CONDITIONAL_ATTRIBUTE_MISSING;
+	if (Array.isArray(value)) return value.map((item) => sanitizeConditionalAttributes(item)).filter((item) => item !== CONDITIONAL_ATTRIBUTE_MISSING);
+	if (isPlainObject(value)) {
+		const result = {};
+		for (const [key, nestedValue] of Object.entries(value)) {
+			const sanitizedValue = sanitizeConditionalAttributes(nestedValue);
+			if (sanitizedValue === CONDITIONAL_ATTRIBUTE_MISSING) continue;
+			result[key] = sanitizedValue;
+		}
+		return result;
+	}
+	return value;
+};
+
+//#endregion
+//#region src/utilities/case.ts
+const splitWords = (str) => {
+	return str.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/[-_\s]+/g, " ").trim().toLowerCase().split(" ").filter(Boolean);
+};
+const toCamelCase = (str) => {
+	return splitWords(str).map((w, i) => i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1)).join("");
+};
+const toSnakeCase = (str) => {
+	return splitWords(str).join("_");
+};
+const toPascalCase = (str) => {
+	return splitWords(str).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+};
+const toKebabCase = (str) => {
+	return splitWords(str).join("-");
+};
+const getCaseTransformer = (style) => {
+	if (typeof style === "function") return style;
+	switch (style) {
+		case "camel": return toCamelCase;
+		case "snake": return toSnakeCase;
+		case "pascal": return toPascalCase;
+		case "kebab": return toKebabCase;
+	}
+};
+const transformKeys = (obj, transformer) => {
+	if (obj === null || obj === void 0) return obj;
+	if (Array.isArray(obj)) return obj.map((item) => transformKeys(item, transformer));
+	if (obj instanceof Date || obj instanceof RegExp) return obj;
+	if (typeof obj === "object") return Object.fromEntries(Object.entries(obj).map(([key, value]) => [transformer(key), transformKeys(value, transformer)]));
+	return obj;
+};
+
+//#endregion
+//#region src/utilities/config.ts
 let stubsDir = path.resolve(process.cwd(), "node_modules/resora/stubs");
 if (!existsSync(stubsDir)) stubsDir = path.resolve(process.cwd(), "stubs");
 const getDefaultConfig = () => {
 	return {
 		stubsDir,
 		preferredCase: "camel",
+		responseStructure: {
+			wrap: true,
+			rootKey: "data"
+		},
 		paginatedExtras: ["meta", "links"],
+		baseUrl: "https://localhost",
+		pageName: "page",
 		paginatedLinks: {
 			first: "first",
 			last: "last",
@@ -38,6 +371,10 @@ const getDefaultConfig = () => {
 			last_page: "last_page",
 			current_page: "current_page"
 		},
+		cursorMeta: {
+			previous: "previous",
+			next: "next"
+		},
 		resourcesDir: "src/resources",
 		stubs: {
 			config: "resora.config.stub",
@@ -46,12 +383,6 @@ const getDefaultConfig = () => {
 		}
 	};
 };
-/**
-* Define the configuration for the package
-* 
-* @param userConfig  The user configuration to override the default configuration
-* @returns The merged configuration object
-*/
 const defineConfig = (userConfig = {}) => {
 	const defaultConfig = getDefaultConfig();
 	return Object.assign(defaultConfig, userConfig, { stubs: Object.assign(defaultConfig.stubs, userConfig.stubs || {}) });
@@ -82,6 +413,13 @@ var CliApp = class {
 		return this;
 	}
 	/**
+	* Get the current configuration object
+	* @returns 
+	*/
+	getConfig() {
+		return this.config;
+	}
+	/**
 	* Initialize Resora by creating a default config file in the current directory
 	* 
 	* @returns 
@@ -163,6 +501,20 @@ var CliApp = class {
 	}
 };
 
+//#endregion
+//#region src/cli/commands/InitCommand.ts
+var InitCommand = class extends Command {
+	signature = `init
+        {--force : Force overwrite if config file already exists (existing file will be backed up) }
+    `;
+	description = "Initialize Resora";
+	async handle() {
+		this.app.command = this;
+		this.app.init();
+		this.success("Resora initialized");
+	}
+};
+
 //#endregion
 //#region src/cli/commands/MakeResource.ts
 var MakeResource = class extends Command {
@@ -340,10 +692,21 @@ var ServerResponse = class {
 /**
 * GenericResource class to handle API resource transformation and response building
 */
-var GenericResource = class {
+var GenericResource = class GenericResource {
 	body = { data: {} };
 	resource;
 	collects;
+	additionalMeta;
+	withResponseContext;
+	/**
+	* Preferred case style for this resource's output keys.
+	* Set on a subclass to override the global default.
+	*/
+	static preferredCase;
+	/**
+	* Response structure override for this generic resource class.
+	*/
+	static responseStructure;
 	called = {};
 	constructor(rsc, res) {
 		this.res = res;
@@ -373,6 +736,52 @@ var GenericResource = class {
 		return this.resource;
 	}
 	/**
+	* Get the current serialized output body.
+	*/
+	getBody() {
+		this.json();
+		return this.body;
+	}
+	/**
+	* Replace the current serialized output body.
+	*/
+	setBody(body) {
+		this.body = body;
+		return this;
+	}
+	/**
+	* Conditionally include a value in serialized output.
+	*/
+	when(condition, value) {
+		return resolveWhen(condition, value);
+	}
+	/**
+	* Include a value only when it is not null/undefined.
+	*/
+	whenNotNull(value) {
+		return resolveWhenNotNull(value);
+	}
+	/**
+	* Conditionally merge object attributes into serialized output.
+	*/
+	mergeWhen(condition, value) {
+		return resolveMergeWhen(condition, value);
+	}
+	resolveResponseStructure() {
+		const local = this.constructor.responseStructure;
+		const collectsLocal = this.collects?.responseStructure;
+		const global = getGlobalResponseStructure();
+		return {
+			wrap: local?.wrap ?? collectsLocal?.wrap ?? global?.wrap ?? true,
+			rootKey: local?.rootKey ?? collectsLocal?.rootKey ?? global?.rootKey ?? "data",
+			factory: local?.factory ?? collectsLocal?.factory ?? global?.factory
+		};
+	}
+	getPayloadKey() {
+		const { wrap, rootKey, factory } = this.resolveResponseStructure();
+		return factory || !wrap ? void 0 : rootKey;
+	}
+	/**
 	* Convert resource to JSON response format
 	* 
 	* @returns 
@@ -387,13 +796,65 @@ var GenericResource = class {
 				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 };
+			data = sanitizeConditionalAttributes(data);
+			const paginationExtras = buildPaginationExtras(this.resource);
+			const { metaKey } = getPaginationExtraKeys();
+			const configuredMeta = metaKey ? paginationExtras[metaKey] : void 0;
+			if (metaKey) delete paginationExtras[metaKey];
+			const caseStyle = this.constructor.preferredCase ?? getGlobalCase();
+			if (caseStyle) {
+				const transformer = getCaseTransformer(caseStyle);
+				data = transformKeys(data, transformer);
+			}
+			const customMeta = mergeMetadata(resolveWithHookMetadata(this, GenericResource.prototype.with), this.additionalMeta);
+			const { wrap, rootKey, factory } = this.resolveResponseStructure();
+			this.body = buildResponseEnvelope({
+				payload: data,
+				meta: configuredMeta,
+				metaKey,
+				wrap,
+				rootKey,
+				factory,
+				context: {
+					type: "generic",
+					resource: this.resource
+				}
+			});
+			this.body = appendRootProperties(this.body, {
+				...paginationExtras,
+				...customMeta || {}
+			}, rootKey);
+		}
+		return this;
+	}
+	/**
+	* Append structured metadata to the response body.
+	*
+	* @param meta  Metadata object or metadata factory
+	* @returns
+	*/
+	with(meta) {
+		this.called.with = true;
+		if (typeof meta === "undefined") return this.additionalMeta || {};
+		const resolvedMeta = typeof meta === "function" ? meta(this.resource) : meta;
+		this.additionalMeta = mergeMetadata(this.additionalMeta, resolvedMeta);
+		if (this.called.json) {
+			const { rootKey } = this.resolveResponseStructure();
+			this.body = appendRootProperties(this.body, resolvedMeta, rootKey);
 		}
 		return this;
 	}
 	/**
+	* Typed fluent metadata helper.
+	*
+	* @param meta  Metadata object or metadata factory
+	* @returns
+	*/
+	withMeta(meta) {
+		this.with(meta);
+		return this;
+	}
+	/**
 	* Convert resource to array format (for collections)
 	*
 	* @returns
@@ -414,8 +875,14 @@ var GenericResource = class {
 	additional(extra) {
 		this.called.additional = true;
 		this.json();
+		const extraData = extra.data;
 		delete extra.data;
 		delete extra.pagination;
+		const payloadKey = this.getPayloadKey();
+		if (extraData && payloadKey && typeof this.body[payloadKey] !== "undefined") this.body[payloadKey] = Array.isArray(this.body[payloadKey]) ? [...this.body[payloadKey], ...extraData] : {
+			...this.body[payloadKey],
+			...extraData
+		};
 		this.body = {
 			...this.body,
 			...extra
@@ -424,7 +891,24 @@ var GenericResource = class {
 	}
 	response(res) {
 		this.called.toResponse = true;
-		return new ServerResponse(res ?? this.res, this.body);
+		this.json();
+		const rawResponse = res ?? this.res;
+		const response = new ServerResponse(rawResponse, this.body);
+		this.withResponseContext = {
+			response,
+			raw: rawResponse
+		};
+		this.called.withResponse = true;
+		this.withResponse(response, rawResponse);
+		return response;
+	}
+	/**
+	* Customize the outgoing transport response right before dispatch.
+	*
+	* Override in custom classes to mutate headers/status/body.
+	*/
+	withResponse(_response, _rawResponse) {
+		return this;
 	}
 	/**
 	* Promise-like then method to allow chaining with async/await or .then() syntax
@@ -436,6 +920,18 @@ var GenericResource = class {
 	then(onfulfilled, onrejected) {
 		this.called.then = true;
 		this.json();
+		if (this.res) {
+			const response = new ServerResponse(this.res, this.body);
+			this.withResponseContext = {
+				response,
+				raw: this.res
+			};
+			this.called.withResponse = true;
+			this.withResponse(response, this.res);
+		} else {
+			this.called.withResponse = true;
+			this.withResponse();
+		}
 		const resolved = Promise.resolve(this.body).then(onfulfilled, onrejected);
 		if (this.res) this.res.send(this.body);
 		return resolved;
@@ -447,10 +943,21 @@ var GenericResource = class {
 /**
 * ResourceCollection class to handle API resource transformation and response building for collections
 */
-var ResourceCollection = class {
+var ResourceCollection = class ResourceCollection {
 	body = { data: [] };
 	resource;
 	collects;
+	additionalMeta;
+	withResponseContext;
+	/**
+	* Preferred case style for this collection's output keys.
+	* Set on a subclass to override the global default.
+	*/
+	static preferredCase;
+	/**
+	* Response structure override for this collection class.
+	*/
+	static responseStructure;
 	called = {};
 	constructor(rsc, res) {
 		this.res = res;
@@ -463,6 +970,52 @@ var ResourceCollection = class {
 		return this.toArray();
 	}
 	/**
+	* Get the current serialized output body.
+	*/
+	getBody() {
+		this.json();
+		return this.body;
+	}
+	/**
+	* Replace the current serialized output body.
+	*/
+	setBody(body) {
+		this.body = body;
+		return this;
+	}
+	/**
+	* Conditionally include a value in serialized output.
+	*/
+	when(condition, value) {
+		return resolveWhen(condition, value);
+	}
+	/**
+	* Include a value only when it is not null/undefined.
+	*/
+	whenNotNull(value) {
+		return resolveWhenNotNull(value);
+	}
+	/**
+	* Conditionally merge object attributes into serialized output.
+	*/
+	mergeWhen(condition, value) {
+		return resolveMergeWhen(condition, value);
+	}
+	resolveResponseStructure() {
+		const local = this.constructor.responseStructure;
+		const collectsLocal = this.collects?.responseStructure;
+		const global = getGlobalResponseStructure();
+		return {
+			wrap: local?.wrap ?? collectsLocal?.wrap ?? global?.wrap ?? true,
+			rootKey: local?.rootKey ?? collectsLocal?.rootKey ?? global?.rootKey ?? "data",
+			factory: local?.factory ?? collectsLocal?.factory ?? global?.factory
+		};
+	}
+	getPayloadKey() {
+		const { wrap, rootKey, factory } = this.resolveResponseStructure();
+		return factory || !wrap ? void 0 : rootKey;
+	}
+	/**
 	* Convert resource to JSON response format
 	* 
 	* @returns 
@@ -472,19 +1025,65 @@ var ResourceCollection = class {
 			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 };
+			data = sanitizeConditionalAttributes(data);
+			const paginationExtras = !Array.isArray(this.resource) ? buildPaginationExtras(this.resource) : {};
+			const { metaKey } = getPaginationExtraKeys();
+			const configuredMeta = metaKey ? paginationExtras[metaKey] : void 0;
+			if (metaKey) delete paginationExtras[metaKey];
+			const caseStyle = this.constructor.preferredCase ?? this.collects?.preferredCase ?? getGlobalCase();
+			if (caseStyle) {
+				const transformer = getCaseTransformer(caseStyle);
+				data = transformKeys(data, transformer);
 			}
+			const customMeta = mergeMetadata(resolveWithHookMetadata(this, ResourceCollection.prototype.with), this.additionalMeta);
+			const { wrap, rootKey, factory } = this.resolveResponseStructure();
+			this.body = buildResponseEnvelope({
+				payload: data,
+				meta: configuredMeta,
+				metaKey,
+				wrap,
+				rootKey,
+				factory,
+				context: {
+					type: "collection",
+					resource: this.resource
+				}
+			});
+			this.body = appendRootProperties(this.body, {
+				...paginationExtras,
+				...customMeta || {}
+			}, rootKey);
 		}
 		return this;
 	}
 	/**
+	* Append structured metadata to the response body.
+	*
+	* @param meta  Metadata object or metadata factory
+	* @returns
+	*/
+	with(meta) {
+		this.called.with = true;
+		if (typeof meta === "undefined") return this.additionalMeta || {};
+		const resolvedMeta = typeof meta === "function" ? meta(this.resource) : meta;
+		this.additionalMeta = mergeMetadata(this.additionalMeta, resolvedMeta);
+		if (this.called.json) {
+			const { rootKey } = this.resolveResponseStructure();
+			this.body = appendRootProperties(this.body, resolvedMeta, rootKey);
+		}
+		return this;
+	}
+	/**
+	* Typed fluent metadata helper.
+	*
+	* @param meta  Metadata object or metadata factory
+	* @returns
+	*/
+	withMeta(meta) {
+		this.with(meta);
+		return this;
+	}
+	/**
 	* Flatten resource to return original data
 	*
 	* @returns
@@ -505,7 +1104,8 @@ var ResourceCollection = class {
 		this.json();
 		delete extra.cursor;
 		delete extra.pagination;
-		if (extra.data && Array.isArray(this.body.data)) this.body.data = [...this.body.data, ...extra.data];
+		const payloadKey = this.getPayloadKey();
+		if (extra.data && payloadKey && Array.isArray(this.body[payloadKey])) this.body[payloadKey] = [...this.body[payloadKey], ...extra.data];
 		this.body = {
 			...this.body,
 			...extra
@@ -514,7 +1114,24 @@ var ResourceCollection = class {
 	}
 	response(res) {
 		this.called.toResponse = true;
-		return new ServerResponse(res ?? this.res, this.body);
+		this.json();
+		const rawResponse = res ?? this.res;
+		const response = new ServerResponse(rawResponse, this.body);
+		this.withResponseContext = {
+			response,
+			raw: rawResponse
+		};
+		this.called.withResponse = true;
+		this.withResponse(response, rawResponse);
+		return response;
+	}
+	/**
+	* Customize the outgoing transport response right before dispatch.
+	*
+	* Override in custom classes to mutate headers/status/body.
+	*/
+	withResponse(_response, _rawResponse) {
+		return this;
 	}
 	setCollects(collects) {
 		this.collects = collects;
@@ -530,6 +1147,18 @@ var ResourceCollection = class {
 	then(onfulfilled, onrejected) {
 		this.called.then = true;
 		this.json();
+		if (this.res) {
+			const response = new ServerResponse(this.res, this.body);
+			this.withResponseContext = {
+				response,
+				raw: this.res
+			};
+			this.called.withResponse = true;
+			this.withResponse(response, this.res);
+		} else {
+			this.called.withResponse = true;
+			this.withResponse();
+		}
 		const resolved = Promise.resolve(this.body).then(onfulfilled, onrejected);
 		if (this.res) this.res.send(this.body);
 		return resolved;
@@ -559,9 +1188,20 @@ var ResourceCollection = class {
 /**
 * Resource class to handle API resource transformation and response building
 */
-var Resource = class {
+var Resource = class Resource {
 	body = { data: {} };
 	resource;
+	additionalMeta;
+	withResponseContext;
+	/**
+	* Preferred case style for this resource's output keys.
+	* Set on a subclass to override the global default.
+	*/
+	static preferredCase;
+	/**
+	* Response structure override for this resource class.
+	*/
+	static responseStructure;
 	called = {};
 	constructor(rsc, res) {
 		this.res = res;
@@ -600,6 +1240,51 @@ var Resource = class {
 		return this.toArray();
 	}
 	/**
+	* Get the current serialized output body.
+	*/
+	getBody() {
+		this.json();
+		return this.body;
+	}
+	/**
+	* Replace the current serialized output body.
+	*/
+	setBody(body) {
+		this.body = body;
+		return this;
+	}
+	/**
+	* Conditionally include a value in serialized output.
+	*/
+	when(condition, value) {
+		return resolveWhen(condition, value);
+	}
+	/**
+	* Include a value only when it is not null/undefined.
+	*/
+	whenNotNull(value) {
+		return resolveWhenNotNull(value);
+	}
+	/**
+	* Conditionally merge object attributes into serialized output.
+	*/
+	mergeWhen(condition, value) {
+		return resolveMergeWhen(condition, value);
+	}
+	resolveResponseStructure() {
+		const local = this.constructor.responseStructure;
+		const global = getGlobalResponseStructure();
+		return {
+			wrap: local?.wrap ?? global?.wrap ?? true,
+			rootKey: local?.rootKey ?? global?.rootKey ?? "data",
+			factory: local?.factory ?? global?.factory
+		};
+	}
+	getPayloadKey() {
+		const { wrap, rootKey, factory } = this.resolveResponseStructure();
+		return factory || !wrap ? void 0 : rootKey;
+	}
+	/**
 	* Convert resource to JSON response format
 	* 
 	* @returns 
@@ -610,11 +1295,56 @@ var Resource = class {
 			const resource = this.data();
 			let data = Array.isArray(resource) ? [...resource] : { ...resource };
 			if (typeof data.data !== "undefined") data = data.data;
-			this.body = { data };
+			data = sanitizeConditionalAttributes(data);
+			const caseStyle = this.constructor.preferredCase ?? getGlobalCase();
+			if (caseStyle) {
+				const transformer = getCaseTransformer(caseStyle);
+				data = transformKeys(data, transformer);
+			}
+			const customMeta = mergeMetadata(resolveWithHookMetadata(this, Resource.prototype.with), this.additionalMeta);
+			const { wrap, rootKey, factory } = this.resolveResponseStructure();
+			this.body = buildResponseEnvelope({
+				payload: data,
+				wrap,
+				rootKey,
+				factory,
+				context: {
+					type: "resource",
+					resource: this.resource
+				}
+			});
+			this.body = appendRootProperties(this.body, customMeta, rootKey);
 		}
 		return this;
 	}
 	/**
+	* Append structured metadata to the response body.
+	*
+	* @param meta  Metadata object or metadata factory
+	* @returns
+	*/
+	with(meta) {
+		this.called.with = true;
+		if (typeof meta === "undefined") return this.additionalMeta || {};
+		const resolvedMeta = typeof meta === "function" ? meta(this.resource) : meta;
+		this.additionalMeta = mergeMetadata(this.additionalMeta, resolvedMeta);
+		if (this.called.json) {
+			const { rootKey } = this.resolveResponseStructure();
+			this.body = appendRootProperties(this.body, resolvedMeta, rootKey);
+		}
+		return this;
+	}
+	/**
+	* Typed fluent metadata helper.
+	*
+	* @param meta  Metadata object or metadata factory
+	* @returns
+	*/
+	withMeta(meta) {
+		this.with(meta);
+		return this;
+	}
+	/**
 	* Flatten resource to array format (for collections) or return original data for single resources
 	*
 	* @returns
@@ -635,8 +1365,9 @@ var Resource = class {
 	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,
+		const payloadKey = this.getPayloadKey();
+		if (extra.data && payloadKey && typeof this.body[payloadKey] !== "undefined") this.body[payloadKey] = Array.isArray(this.body[payloadKey]) ? [...this.body[payloadKey], ...extra.data] : {
+			...this.body[payloadKey],
 			...extra.data
 		};
 		this.body = {
@@ -647,7 +1378,24 @@ var Resource = class {
 	}
 	response(res) {
 		this.called.toResponse = true;
-		return new ServerResponse(res ?? this.res, this.body);
+		this.json();
+		const rawResponse = res ?? this.res;
+		const response = new ServerResponse(rawResponse, this.body);
+		this.withResponseContext = {
+			response,
+			raw: rawResponse
+		};
+		this.called.withResponse = true;
+		this.withResponse(response, rawResponse);
+		return response;
+	}
+	/**
+	* Customize the outgoing transport response right before dispatch.
+	*
+	* Override in custom classes to mutate headers/status/body.
+	*/
+	withResponse(_response, _rawResponse) {
+		return this;
 	}
 	/**
 	* Promise-like then method to allow chaining with async/await or .then() syntax
@@ -659,6 +1407,18 @@ var Resource = class {
 	then(onfulfilled, onrejected) {
 		this.called.then = true;
 		this.json();
+		if (this.res) {
+			const response = new ServerResponse(this.res, this.body);
+			this.withResponseContext = {
+				response,
+				raw: this.res
+			};
+			this.called.withResponse = true;
+			this.withResponse(response, this.res);
+		} else {
+			this.called.withResponse = true;
+			this.withResponse();
+		}
 		const resolved = Promise.resolve(this.body).then(onfulfilled, onrejected);
 		if (this.res) this.res.send(this.body);
 		return resolved;
@@ -684,4 +1444,4 @@ var Resource = class {
 };
 
 //#endregion
-export { ApiResource, CliApp, GenericResource, MakeResource, Resource, ResourceCollection, ServerResponse, defineConfig, getDefaultConfig };
+export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CliApp, GenericResource, InitCommand, MakeResource, Resource, ResourceCollection, ServerResponse, appendRootProperties, buildPaginationExtras, buildResponseEnvelope, defineConfig, getCaseTransformer, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, isPlainObject, mergeMetadata, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, sanitizeConditionalAttributes, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };