resora 0.2.0 → 0.2.2

package/bin/index.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,rmSync as i,writeFileSync as a}from"fs";import o,{dirname as s,join as c}from"path";import{Command as l,Kernel as u}from"@h3ravel/musket";let d=o.resolve(process.cwd(),`node_modules/resora/stubs`);t(d)||(d=o.resolve(process.cwd(),`stubs`));const f=()=>({stubsDir:d,preferredCase:`camel`,responseStructure:{wrap:!0,rootKey:`data`},paginatedExtras:[`meta`,`links`],baseUrl:`https://localhost`,pageName:`page`,paginatedLinks:{first:`first`,last:`last`,prev:`prev`,next:`next`},paginatedMeta:{to:`to`,from:`from`,links:`links`,path:`path`,total:`total`,per_page:`per_page`,last_page:`last_page`,current_page:`current_page`},cursorMeta:{previous:`previous`,next:`next`},resourcesDir:`src/resources`,stubs:{config:`resora.config.stub`,resource:`resource.stub`,collection:`resource.collection.stub`}}),p=(e={})=>{let t=f();return Object.assign(t,e,{stubs:Object.assign(t.stubs,e.stubs||{})})};var m=class{command;config={};constructor(e={}){this.config=p(e)}async loadConfig(e={}){this.config=p(e);let n=[c(process.cwd(),`resora.config.ts`),c(process.cwd(),`resora.config.js`),c(process.cwd(),`resora.config.cjs`)];for(let e of n)if(t(e))try{let{default:t}=await import(e);Object.assign(this.config,t);break}catch(t){console.error(`Error loading config file at ${e}:`,t)}return this}getConfig(){return this.config}init(){let n=c(process.cwd(),`resora.config.js`),i=c(this.config.stubsDir,this.config.stubs.config);return t(n)&&!this.command.option(`force`)&&(this.command.error(`Error: ${n} already exists.`),process.exit(1)),this.ensureDirectory(n),t(n)&&this.command.option(`force`)&&e(n,n.replace(/\.js$/,`.backup.${Date.now()}.js`)),a(n,r(i,`utf-8`)),{path:n}}ensureDirectory(e){let r=s(e);t(r)||n(r,{recursive:!0})}generateFile(e,n,o,s){t(n)&&!s?.force?(this.command.error(`Error: ${n} already exists.`),process.exit(1)):t(n)&&s?.force&&i(n);let c=r(e,`utf-8`);for(let[e,t]of Object.entries(o))c=c.replace(RegExp(`{{${e}}}`,`g`),t);return this.ensureDirectory(n),a(n,c),n}makeResource(e,n){let r=e;n?.collection&&!e.endsWith(`Collection`)&&!e.endsWith(`Resource`)?r+=`Collection`:!n?.collection&&!e.endsWith(`Resource`)&&!e.endsWith(`Collection`)&&(r+=`Resource`);let i=`${r}.ts`,a=c(this.config.resourcesDir,i),o=c(this.config.stubsDir,n?.collection||e.endsWith(`Collection`)?this.config.stubs.collection:this.config.stubs.resource);t(o)||(this.command.error(`Error: Stub file ${o} not found.`),process.exit(1));let s=r.replace(/(Resource|Collection)$/,``)+`Resource`,l=`/** 
+import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,rmSync as i,writeFileSync as a}from"fs";import o,{dirname as s,join as c}from"path";import{createRequire as l}from"module";import{pathToFileURL as u}from"url";import{Command as d,Kernel as f}from"@h3ravel/musket";let p={first:`first`,last:`last`,prev:`prev`,next:`next`},m={to:`to`,from:`from`,links:`links`,path:`path`,total:`total`,per_page:`per_page`,last_page:`last_page`,current_page:`current_page`},h={previous:`previous`,next:`next`};const g=e=>{p={...p,...e}},_=e=>{m={...m,...e}},v=e=>{h={...h,...e}};let y=o.resolve(process.cwd(),`node_modules/resora/stubs`);t(y)||(y=o.resolve(process.cwd(),`stubs`));const b=()=>({stubsDir:y,preferredCase:`camel`,responseStructure:{wrap:!0,rootKey:`data`},paginatedExtras:[`meta`,`links`],baseUrl:`https://localhost`,pageName:`page`,paginatedLinks:{first:`first`,last:`last`,prev:`prev`,next:`next`},paginatedMeta:{to:`to`,from:`from`,links:`links`,path:`path`,total:`total`,per_page:`per_page`,last_page:`last_page`,current_page:`current_page`},cursorMeta:{previous:`previous`,next:`next`},resourcesDir:`src/resources`,stubs:{config:`resora.config.stub`,resource:`resource.stub`,collection:`resource.collection.stub`}}),x=e=>{let t=b();return Object.assign(t,e,{stubs:Object.assign(t.stubs,e.stubs||{})},{cursorMeta:Object.assign(t.cursorMeta,e.cursorMeta||{})},{paginatedMeta:Object.assign(t.paginatedMeta,e.paginatedMeta||{})},{paginatedLinks:Object.assign(t.paginatedLinks,e.paginatedLinks||{})},{responseStructure:Object.assign(t.responseStructure,e.responseStructure||{})})};let S=!1,C;const w=e=>{e.preferredCase!==`camel`&&e.preferredCase,e.responseStructure,e.paginatedExtras,g(e.paginatedLinks),_(e.paginatedMeta),v(e.cursorMeta),e.baseUrl,e.pageName},T=async e=>await import(`${u(e).href}?resora_runtime=${Date.now()}`),E=e=>{w(x((e?.default??e)||{})),S=!0},D=()=>{let e=l(import.meta.url),n=[o.join(process.cwd(),`resora.config.cjs`)];for(let r of n)if(t(r))try{return E(e(r)),!0}catch{continue}return!1};(async()=>{if(!S){if(C)return await C;D()||(C=(async()=>{let e=[o.join(process.cwd(),`resora.config.js`),o.join(process.cwd(),`resora.config.ts`)];for(let n of e)if(t(n))try{E(await T(n));return}catch{continue}S=!0})(),await C)}})();var O=class{command;config={};constructor(e={}){this.config=x(e)}async loadConfig(e={}){this.config=x(e);let n=[c(process.cwd(),`resora.config.ts`),c(process.cwd(),`resora.config.js`),c(process.cwd(),`resora.config.cjs`)];for(let e of n)if(t(e))try{let{default:t}=await import(e);Object.assign(this.config,t);break}catch(t){console.error(`Error loading config file at ${e}:`,t)}return this}getConfig(){return this.config}init(){let n=c(process.cwd(),`resora.config.js`),i=c(this.config.stubsDir,this.config.stubs.config);return t(n)&&!this.command.option(`force`)&&(this.command.error(`Error: ${n} already exists.`),process.exit(1)),this.ensureDirectory(n),t(n)&&this.command.option(`force`)&&e(n,n.replace(/\.js$/,`.backup.${Date.now()}.js`)),a(n,r(i,`utf-8`)),{path:n}}ensureDirectory(e){let r=s(e);t(r)||n(r,{recursive:!0})}generateFile(e,n,o,s){t(n)&&!s?.force?(this.command.error(`Error: ${n} already exists.`),process.exit(1)):t(n)&&s?.force&&i(n);let c=r(e,`utf-8`);for(let[e,t]of Object.entries(o))c=c.replace(RegExp(`{{${e}}}`,`g`),t);return this.ensureDirectory(n),a(n,c),n}makeResource(e,n){let r=e;n?.collection&&!e.endsWith(`Collection`)&&!e.endsWith(`Resource`)?r+=`Collection`:!n?.collection&&!e.endsWith(`Resource`)&&!e.endsWith(`Collection`)&&(r+=`Resource`);let i=`${r}.ts`,a=c(this.config.resourcesDir,i),o=c(this.config.stubsDir,n?.collection||e.endsWith(`Collection`)?this.config.stubs.collection:this.config.stubs.resource);t(o)||(this.command.error(`Error: Stub file ${o} not found.`),process.exit(1));let s=r.replace(/(Resource|Collection)$/,``)+`Resource`,l=`/** 
      * The resource that this collection collects.
      */
     collects = ${s}
-    `,u=`import ${s} from './${s}'\n`,d=(!!n?.collection||e.endsWith(`Collection`))&&t(c(this.config.resourcesDir,`${s}.ts`)),f=this.generateFile(o,a,{ResourceName:r,CollectionResourceName:r.replace(/(Resource|Collection)$/,``)+`Resource`,"collects = Resource":d?l:``,"import = Resource":d?u:``},n);return{name:r,path:f}}},h=class extends l{signature=`init
+    `,u=`import ${s} from './${s}'\n`,d=(!!n?.collection||e.endsWith(`Collection`))&&t(c(this.config.resourcesDir,`${s}.ts`)),f=this.generateFile(o,a,{ResourceName:r,CollectionResourceName:r.replace(/(Resource|Collection)$/,``)+`Resource`,"collects = Resource":d?l:``,"import = Resource":d?u:``},n);return{name:r,path:f}}},k=class extends d{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`)}},g=class extends l{signature=`#create:
+    `;description=`Initialize Resora`;async handle(){this.app.command=this,this.app.init(),this.success(`Resora initialized`)}},A=class extends d{signature=`#create:
         {resource : Generates a new resource file.
             | {name : Name of the resource to create}
             | {--c|collection : Make a resource collection}
@@ -19,11 +19,11 @@ import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,rmSync
             | {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 e=``,t=this.dictionary.name||this.dictionary.baseCommand;if([`resource`,`collection`].includes(t)&&!this.argument(`name`))return void this.error(`Error: Name argument is required.`);if(t===`all`&&!this.argument(`prefix`))return void this.error(`Error: Prefix argument is required.`);switch(t){case`resource`:({path:e}=this.app.makeResource(this.argument(`name`),this.options()));break;case`collection`:({path:e}=this.app.makeResource(this.argument(`name`)+`Collection`,this.options()));break;case`all`:{let t=this.app.makeResource(this.argument(`prefix`),{force:this.option(`force`)}),n=this.app.makeResource(this.argument(`prefix`)+`Collection`,{collection:!0,force:this.option(`force`)});e=`${t.path}, ${n.path}`;break}default:this.fail(`Unknown action: ${t}`)}this.success(`Created: ${e}`)}},_=String.raw`
+    `;description=`Create a new resource or resource collection file`;async handle(){this.app.command=this;let e=``,t=this.dictionary.name||this.dictionary.baseCommand;if([`resource`,`collection`].includes(t)&&!this.argument(`name`))return void this.error(`Error: Name argument is required.`);if(t===`all`&&!this.argument(`prefix`))return void this.error(`Error: Prefix argument is required.`);switch(t){case`resource`:({path:e}=this.app.makeResource(this.argument(`name`),this.options()));break;case`collection`:({path:e}=this.app.makeResource(this.argument(`name`)+`Collection`,this.options()));break;case`all`:{let t=this.app.makeResource(this.argument(`prefix`),{force:this.option(`force`)}),n=this.app.makeResource(this.argument(`prefix`)+`Collection`,{collection:!0,force:this.option(`force`)});e=`${t.path}, ${n.path}`;break}default:this.fail(`Unknown action: ${t}`)}this.success(`Created: ${e}`)}},j=String.raw`
   _____                           
  |  __ \                          
  | |__) |___  ___  ___  _ __ __ _ 
  |  _  // _ \/ __|/ _ \| '__/ _, |
  | | \ \  __/\__ \ (_) | | | (_| |
  |_|  \_\___||___/\___/|_|  \__,_|                                                                                           
-`;const v=new m;await u.init(await v.loadConfig(),{logo:_,name:`Resora CLI`,baseCommands:[g,h,...v.getConfig().extraCommands||[]],exceptionHandler(e){throw e}});export{};
+`;const M=new O;await f.init(await M.loadConfig(),{logo:j,name:`Resora CLI`,baseCommands:[A,k,...M.getConfig().extraCommands||[]],exceptionHandler(e){throw e}});export{};

package/dist/index.cjs

@@ -29,6 +29,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let fs = require("fs");
 let path = require("path");
 path = __toESM(path);
+let module$1 = require("module");
+let url = require("url");
 let _h3ravel_musket = require("@h3ravel/musket");
 
 //#region src/ApiResource.ts
@@ -69,93 +71,227 @@ let globalCursorMeta = {
 	previous: "previous",
 	next: "next"
 };
+/**
+* Sets the global case style for response keys, which will be applied 
+* to all responses unless overridden by individual resource configurations.
+* 
+* @param style The case style to set as the global default for response keys. 
+*/
 const setGlobalCase = (style) => {
 	globalPreferredCase = style;
 };
+/**
+* Retrieves the global case style for response keys, which is used 
+* to determine how keys in responses should be formatted.
+* 
+* @returns 
+*/
 const getGlobalCase = () => {
 	return globalPreferredCase;
 };
+/**
+* Sets the global response structure configuration, which defines how 
+* responses should be structured across the application.
+* 
+* @param config The response structure configuration object.
+*/
 const setGlobalResponseStructure = (config) => {
 	globalResponseStructure = config;
 };
+/**
+* Retrieves the global response structure configuration, which 
+* defines how  responses should be structured across the application.
+* 
+* @returns 
+*/
 const getGlobalResponseStructure = () => {
 	return globalResponseStructure;
 };
+/**
+* Sets the global response root key, which is the key under which 
+* the main data will be nested in responses if wrapping is enabled.
+* 
+* @param rootKey The root key to set for response data.
+*/
 const setGlobalResponseRootKey = (rootKey) => {
 	globalResponseStructure = {
 		...globalResponseStructure || {},
 		rootKey
 	};
 };
+/**
+* Sets the global response wrap option, which determines whether responses 
+* should be wrapped in a root key or returned unwrapped when possible.
+* 
+* @param wrap The wrap option to set for responses.
+*/
 const setGlobalResponseWrap = (wrap) => {
 	globalResponseStructure = {
 		...globalResponseStructure || {},
 		wrap
 	};
 };
+/**
+* Retrieves the global response wrap option, which indicates whether responses 
+* should be wrapped in a root key or returned unwrapped when possible.
+* 
+* @returns 
+*/
 const getGlobalResponseWrap = () => {
 	return globalResponseStructure?.wrap;
 };
+/**
+* Retrieves the global response root key, which is the key under which the main 
+* data will be nested in responses if wrapping is enabled.
+* 
+* @returns 
+*/
 const getGlobalResponseRootKey = () => {
 	return globalResponseStructure?.rootKey;
 };
+/**
+* Sets the global response factory, which is a custom function that can be used 
+* to produce a completely custom response structure based on the provided 
+* payload and context.
+* 
+* @param factory The response factory function to set as the global default for response construction.
+*/
 const setGlobalResponseFactory = (factory) => {
 	globalResponseStructure = {
 		...globalResponseStructure || {},
 		factory
 	};
 };
+/**
+* Retrieves the global response factory, which is a custom function that 
+* can be used to produce a completely custom response structure based on 
+* the provided payload and context.
+* 
+* @returns 
+*/
 const getGlobalResponseFactory = () => {
 	return globalResponseStructure?.factory;
 };
+/**
+* Sets the global paginated extras configuration, which defines the keys 
+* to use for pagination metadata, links, and cursor information in paginated responses.
+* 
+* @param extras The paginated extras configuration object.
+*/
 const setGlobalPaginatedExtras = (extras) => {
 	globalPaginatedExtras = extras;
 };
+/**
+* Retrieves the global paginated extras configuration, which defines the keys to use for pagination metadata, links, and cursor information in paginated responses.
+* 
+* @returns 
+*/
 const getGlobalPaginatedExtras = () => {
 	return globalPaginatedExtras;
 };
+/**
+* Sets the global paginated links configuration, which defines the keys to 
+* use for pagination links (first, last, prev, next) in paginated responses.
+* 
+* @param links The paginated links configuration object.
+*/
 const setGlobalPaginatedLinks = (links) => {
 	globalPaginatedLinks = {
 		...globalPaginatedLinks,
 		...links
 	};
 };
+/**
+* Retrieves the global paginated links configuration, which defines the keys to use for pagination links (first, last, prev, next) in paginated responses.
+* 
+* @returns 
+*/
 const getGlobalPaginatedLinks = () => {
 	return globalPaginatedLinks;
 };
+/**
+* Sets the global base URL, which is used for generating pagination links in responses.
+* 
+* @param baseUrl The base URL to set for pagination link generation.
+*/
 const setGlobalBaseUrl = (baseUrl) => {
 	globalBaseUrl = baseUrl;
 };
+/**
+* Retrieves the global base URL, which is used for generating pagination links in responses.
+* 
+* @returns 
+*/
 const getGlobalBaseUrl = () => {
 	return globalBaseUrl;
 };
+/**
+* Sets the global page name, which is the query parameter name used for the page number in paginated requests and link generation.
+* 
+* @param pageName 
+*/
 const setGlobalPageName = (pageName) => {
 	globalPageName = pageName;
 };
+/**
+* Retrieves the global page name, which is the query parameter name 
+* used for the page number in paginated requests and link generation.
+* 
+* @returns 
+*/
 const getGlobalPageName = () => {
 	return globalPageName;
 };
+/**
+* Retrieves the keys to use for pagination extras (meta, links, cursor) based 
+* on the global configuration.
+* 
+* @param meta Whether to include pagination metadata in the response.
+*/
 const setGlobalPaginatedMeta = (meta) => {
 	globalPaginatedMeta = {
 		...globalPaginatedMeta,
 		...meta
 	};
 };
+/**
+* Retrieves the keys to use for pagination extras (meta, links, cursor) based 
+* on the global configuration.
+* 
+* @returns The global pagination metadata configuration.
+*/
 const getGlobalPaginatedMeta = () => {
 	return globalPaginatedMeta;
 };
+/**
+* Sets the global cursor meta configuration, which defines the keys to use 
+* for cursor pagination metadata (previous, next) in responses.
+* 
+* @param meta The cursor meta configuration object.
+*/
 const setGlobalCursorMeta = (meta) => {
 	globalCursorMeta = {
 		...globalCursorMeta,
 		...meta
 	};
 };
+/**
+* Retrieves the keys to use for cursor pagination metadata (previous, next) in 
+* responses based on the global configuration.
+* 
+* @returns The global cursor pagination metadata configuration.
+*/
 const getGlobalCursorMeta = () => {
 	return globalCursorMeta;
 };
 
 //#endregion
 //#region src/utilities/pagination.ts
+/**
+* Retrieves the configured keys for pagination extras (meta, links, cursor) based on the application's configuration.
+* 
+* @returns An object containing the keys for meta, links, and cursor extras, or `undefined` if not configured.
+*/
 const getPaginationExtraKeys = () => {
 	const extras = getGlobalPaginatedExtras();
 	if (Array.isArray(extras)) return {
@@ -169,6 +305,13 @@ const getPaginationExtraKeys = () => {
 		cursorKey: extras.cursor
 	};
 };
+/**
+* Builds a pagination URL for a given page number and path, using the global base URL and page name configuration.
+* 
+* @param page The page number for which to build the URL. If `undefined`, the function will return `undefined`.
+* @param pathName The path to use for the URL. If not provided, it will default to an empty string. 
+* @returns 
+*/
 const buildPageUrl = (page, pathName) => {
 	if (typeof page === "undefined") return;
 	const rawPath = pathName || "";
@@ -182,6 +325,13 @@ const buildPageUrl = (page, pathName) => {
 	url.searchParams.set(getGlobalPageName() || "page", String(page));
 	return url.toString();
 };
+/**
+* Builds pagination extras (meta, links, cursor) for a given resource based on 
+* its pagination and cursor properties, using the configured keys for each type of extra.
+* 
+* @param resource The resource for which to build pagination extras. 
+* @returns An object containing the pagination extras (meta, links, cursor) for the resource.
+*/
 const buildPaginationExtras = (resource) => {
 	const { metaKey, linksKey, cursorKey } = getPaginationExtraKeys();
 	const extra = {};
@@ -238,12 +388,26 @@ const buildPaginationExtras = (resource) => {
 
 //#endregion
 //#region src/utilities/objects.ts
+/**
+* Utility functions for working with objects, including type checking, merging, and property manipulation.
+* 
+* @param value The value to check.
+* @returns `true` if the value is a plain object, `false` otherwise.
+*/
 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;
 };
+/**
+* Appends extra properties to a response body, ensuring that the main data is wrapped under a specified root key if necessary.
+* 
+* @param body The original response body, which can be an object, array, or primitive value.
+* @param extra Extra properties to append to the response body.
+* @param rootKey The root key under which to wrap the main data if necessary.
+* @returns The response body with the extra properties appended.
+*/
 const appendRootProperties = (body, extra, rootKey = "data") => {
 	if (!extra || Object.keys(extra).length === 0) return body;
 	if (Array.isArray(body)) return {
@@ -259,6 +423,13 @@ const appendRootProperties = (body, extra, rootKey = "data") => {
 		...extra
 	};
 };
+/**
+* Deeply merges two metadata objects, combining nested objects recursively.
+* 
+* @param base The base metadata object to merge into.
+* @param incoming The incoming metadata object to merge from.
+* @returns 
+*/
 const mergeMetadata = (base, incoming) => {
 	if (!incoming) return base;
 	if (!base) return incoming;
@@ -273,6 +444,12 @@ const mergeMetadata = (base, incoming) => {
 
 //#endregion
 //#region src/utilities/response.ts
+/**
+* Builds a response envelope based on the provided payload, 
+* metadata, and configuration options.
+* 
+* @param config The configuration object containing payload, metadata, and other options for building the response.
+*/
 const buildResponseEnvelope = ({ payload, meta, metaKey = "meta", wrap = true, rootKey = "data", factory, context }) => {
 	if (factory) return factory(payload, {
 		...context,
@@ -297,6 +474,15 @@ const buildResponseEnvelope = ({ payload, meta, metaKey = "meta", wrap = true, r
 
 //#endregion
 //#region src/utilities/metadata.ts
+/**
+* Resolves metadata from a resource instance by checking for a custom `with` method. 
+* If the method exists and is different from the base method, it calls it to retrieve metadata. 
+* This allows resources to provide additional metadata for response construction.
+* 
+* @param instance The resource instance to check for a custom `with` method.
+* @param baseWithMethod The base `with` method to compare against.
+* @returns The resolved metadata or `undefined` if no custom metadata is provided.
+*/
 const resolveWithHookMetadata = (instance, baseWithMethod) => {
 	const candidate = instance?.with;
 	if (typeof candidate !== "function" || candidate === baseWithMethod) return;
@@ -308,18 +494,45 @@ const resolveWithHookMetadata = (instance, baseWithMethod) => {
 //#endregion
 //#region src/utilities/conditional.ts
 const CONDITIONAL_ATTRIBUTE_MISSING = Symbol("resora.conditional.missing");
+/**
+* Resolves a value based on a condition. If the condition is falsy, it returns a special symbol indicating that the attribute is missing. 
+* 
+* 
+* @param condition The condition to evaluate.
+* @param value The value or function to resolve if the condition is truthy.
+* @returns The resolved value or a symbol indicating the attribute is missing.
+*/
 const resolveWhen = (condition, value) => {
 	if (!condition) return CONDITIONAL_ATTRIBUTE_MISSING;
 	return typeof value === "function" ? value() : value;
 };
+/**
+* Resolves a value only if it is not null or undefined. 
+* 
+* @param value The value to resolve.
+* @returns The resolved value or a symbol indicating the attribute is missing.
+*/
 const resolveWhenNotNull = (value) => {
 	return value === null || typeof value === "undefined" ? CONDITIONAL_ATTRIBUTE_MISSING : value;
 };
+/**
+* Conditionally merges object attributes based on a condition. 
+* 
+* @param condition 
+* @param value 
+* @returns 
+*/
 const resolveMergeWhen = (condition, value) => {
 	if (!condition) return {};
 	const resolved = typeof value === "function" ? value() : value;
 	return isPlainObject(resolved) ? resolved : {};
 };
+/**
+*  Recursively sanitizes an object or array by removing any attributes that are marked as missing using the special symbol.
+* 
+* @param value The value to sanitize.
+* @returns The sanitized value.
+*/
 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);
@@ -337,21 +550,58 @@ const sanitizeConditionalAttributes = (value) => {
 
 //#endregion
 //#region src/utilities/case.ts
+/**
+* Splits a string into words based on common delimiters and capitalization patterns.
+* Handles camelCase, PascalCase, snake_case, kebab-case, and space-separated words.
+* 
+* @param str 
+* @returns 
+*/
 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);
 };
+/**
+* Transforms a string to camelCase.
+* 
+* @param str 
+* @returns 
+*/
 const toCamelCase = (str) => {
 	return splitWords(str).map((w, i) => i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1)).join("");
 };
+/**
+* Transforms a string to snake_case.
+* 
+* @param str 
+* @returns 
+*/
 const toSnakeCase = (str) => {
 	return splitWords(str).join("_");
 };
+/**
+* Transforms a string to PascalCase.
+* 
+* @param str 
+* @returns 
+*/
 const toPascalCase = (str) => {
 	return splitWords(str).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
 };
+/**
+* Transforms a string to kebab-case.
+* 
+* @param str 
+* @returns 
+*/
 const toKebabCase = (str) => {
 	return splitWords(str).join("-");
 };
+/**
+* Retrieves the appropriate case transformation function based on the provided style.
+* 
+* @param style 
+* @returns 
+*/
 const getCaseTransformer = (style) => {
 	if (typeof style === "function") return style;
 	switch (style) {
@@ -361,6 +611,14 @@ const getCaseTransformer = (style) => {
 		case "kebab": return toKebabCase;
 	}
 };
+/**
+* Transforms the keys of an object (including nested objects and arrays) using 
+* the provided transformer function.
+* 
+* @param obj 
+* @param transformer 
+* @returns 
+*/
 const transformKeys = (obj, transformer) => {
 	if (obj === null || obj === void 0) return obj;
 	if (Array.isArray(obj)) return obj.map((item) => transformKeys(item, transformer));
@@ -412,10 +670,106 @@ const getDefaultConfig = () => {
 		}
 	};
 };
-const defineConfig = (userConfig = {}) => {
-	const defaultConfig = getDefaultConfig();
-	return Object.assign(defaultConfig, userConfig, { stubs: Object.assign(defaultConfig.stubs, userConfig.stubs || {}) });
+/**
+* Defines the configuration for the application by merging the provided configuration with the default configuration. This function takes a partial configuration object as input and returns a complete configuration object that includes all required properties, using default values for any properties that are not specified in the input.
+* 
+* @param config 
+* @returns 
+*/
+const defineConfig = (config) => {
+	const defConf = getDefaultConfig();
+	return Object.assign(defConf, config, { stubs: Object.assign(defConf.stubs, config.stubs || {}) }, { cursorMeta: Object.assign(defConf.cursorMeta, config.cursorMeta || {}) }, { paginatedMeta: Object.assign(defConf.paginatedMeta, config.paginatedMeta || {}) }, { paginatedLinks: Object.assign(defConf.paginatedLinks, config.paginatedLinks || {}) }, { responseStructure: Object.assign(defConf.responseStructure, config.responseStructure || {}) });
+};
+
+//#endregion
+//#region src/utilities/runtime-config.ts
+let runtimeConfigLoaded = false;
+let runtimeConfigLoadingPromise;
+/**
+* Resets the runtime configuration state for testing purposes.
+* 
+* @returns
+*/
+const resetRuntimeConfigForTests = () => {
+	runtimeConfigLoaded = false;
+	runtimeConfigLoadingPromise = void 0;
+};
+/**
+* Applies the provided configuration to the global state of the application. 
+* 
+* @param config The complete configuration object to apply.
+*/
+const applyRuntimeConfig = (config) => {
+	if (config.preferredCase !== "camel") setGlobalCase(config.preferredCase);
+	setGlobalResponseStructure(config.responseStructure);
+	setGlobalPaginatedExtras(config.paginatedExtras);
+	setGlobalPaginatedLinks(config.paginatedLinks);
+	setGlobalPaginatedMeta(config.paginatedMeta);
+	setGlobalCursorMeta(config.cursorMeta);
+	setGlobalBaseUrl(config.baseUrl);
+	setGlobalPageName(config.pageName);
+};
+/**
+* Loads the runtime configuration by searching for configuration files in the current working directory. 
+* @param configPath The path to the configuration file to load.
+* @returns 
+*/
+const importConfigFile = async (configPath) => {
+	return await import(`${(0, url.pathToFileURL)(configPath).href}?resora_runtime=${Date.now()}`);
+};
+/**
+* Resolves the imported configuration and applies it to the global state.
+* 
+* @param imported 
+*/
+const resolveAndApply = (imported) => {
+	applyRuntimeConfig(defineConfig((imported?.default ?? imported) || {}));
+	runtimeConfigLoaded = true;
+};
+/**
+* Loads the runtime configuration synchronously by searching for CommonJS configuration files in the current working directory. 
+* 
+* @returns 
+*/
+const loadRuntimeConfigSync = () => {
+	const require = (0, module$1.createRequire)(require("url").pathToFileURL(__filename).href);
+	const syncConfigPaths = [path.default.join(process.cwd(), "resora.config.cjs")];
+	for (const configPath of syncConfigPaths) {
+		if (!(0, fs.existsSync)(configPath)) continue;
+		try {
+			resolveAndApply(require(configPath));
+			return true;
+		} catch {
+			continue;
+		}
+	}
+	return false;
+};
+/**
+* Loads the runtime configuration by searching for configuration files in the current working directory. 
+* 
+* @returns 
+*/
+const loadRuntimeConfig = async () => {
+	if (runtimeConfigLoaded) return;
+	if (runtimeConfigLoadingPromise) return await runtimeConfigLoadingPromise;
+	if (loadRuntimeConfigSync()) return;
+	runtimeConfigLoadingPromise = (async () => {
+		const possibleConfigPaths = [path.default.join(process.cwd(), "resora.config.js"), path.default.join(process.cwd(), "resora.config.ts")];
+		for (const configPath of possibleConfigPaths) {
+			if (!(0, fs.existsSync)(configPath)) continue;
+			try {
+				resolveAndApply(await importConfigFile(configPath));
+				return;
+			} catch {
+				continue;
+			}
+		}
+		runtimeConfigLoaded = true;
+	})();
+	await runtimeConfigLoadingPromise;
 };
+loadRuntimeConfig();
 
 //#endregion
 //#region src/cli/CliApp.ts
@@ -517,7 +871,7 @@ var CliApp = class {
     `;
 		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, {
+		const path$3 = this.generateFile(stubPath, outputPath, {
 			ResourceName: resourceName,
 			CollectionResourceName: resourceName.replace(/(Resource|Collection)$/, "") + "Resource",
 			"collects = Resource": hasCollects ? collects : "",
@@ -525,7 +879,7 @@ var CliApp = class {
 		}, options);
 		return {
 			name: resourceName,
-			path: path$2
+			path: path$3
 		};
 	}
 };
@@ -1483,6 +1837,7 @@ exports.Resource = Resource;
 exports.ResourceCollection = ResourceCollection;
 exports.ServerResponse = ServerResponse;
 exports.appendRootProperties = appendRootProperties;
+exports.applyRuntimeConfig = applyRuntimeConfig;
 exports.buildPaginationExtras = buildPaginationExtras;
 exports.buildResponseEnvelope = buildResponseEnvelope;
 exports.defineConfig = defineConfig;
@@ -1501,7 +1856,9 @@ exports.getGlobalResponseStructure = getGlobalResponseStructure;
 exports.getGlobalResponseWrap = getGlobalResponseWrap;
 exports.getPaginationExtraKeys = getPaginationExtraKeys;
 exports.isPlainObject = isPlainObject;
+exports.loadRuntimeConfig = loadRuntimeConfig;
 exports.mergeMetadata = mergeMetadata;
+exports.resetRuntimeConfigForTests = resetRuntimeConfigForTests;
 exports.resolveMergeWhen = resolveMergeWhen;
 exports.resolveWhen = resolveWhen;
 exports.resolveWhenNotNull = resolveWhenNotNull;