resora 0.2.0 → 0.2.2

package/dist/index.mjs

@@ -1,5 +1,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import path, { dirname, join } from "path";
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
 import { Command } from "@h3ravel/musket";
 
 //#region src/ApiResource.ts
@@ -40,93 +42,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 {
@@ -140,6 +276,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 || "";
@@ -153,6 +296,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 = {};
@@ -209,12 +359,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 {
@@ -230,6 +394,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;
@@ -244,6 +415,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,
@@ -268,6 +445,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;
@@ -279,18 +465,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);
@@ -308,21 +521,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) {
@@ -332,6 +582,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));
@@ -383,10 +641,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(`${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 = createRequire(import.meta.url);
+	const syncConfigPaths = [path.join(process.cwd(), "resora.config.cjs")];
+	for (const configPath of syncConfigPaths) {
+		if (!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.join(process.cwd(), "resora.config.js"), path.join(process.cwd(), "resora.config.ts")];
+		for (const configPath of possibleConfigPaths) {
+			if (!existsSync(configPath)) continue;
+			try {
+				resolveAndApply(await importConfigFile(configPath));
+				return;
+			} catch {
+				continue;
+			}
+		}
+		runtimeConfigLoaded = true;
+	})();
+	await runtimeConfigLoadingPromise;
 };
+loadRuntimeConfig();
 
 //#endregion
 //#region src/cli/CliApp.ts
@@ -1444,4 +1798,4 @@ var Resource = class Resource {
 };
 
 //#endregion
-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 };
+export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CliApp, GenericResource, InitCommand, MakeResource, Resource, ResourceCollection, ServerResponse, appendRootProperties, applyRuntimeConfig, buildPaginationExtras, buildResponseEnvelope, defineConfig, getCaseTransformer, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, isPlainObject, loadRuntimeConfig, mergeMetadata, resetRuntimeConfigForTests, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, sanitizeConditionalAttributes, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resora",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A structured API response layer for Node.js and TypeScript with automatic JSON responses, collection support, and pagination handling.",
   "keywords": [
     "api",

package/stubs/resora.config.stub

@@ -1,5 +1,37 @@
 import { defineConfig } from 'resora'
 
 export default defineConfig({
+  preferredCase: 'camel',
+  responseStructure: {
+    wrap: true,
+    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: {
+    resource: 'resource.stub',
+    collection: 'resource.collection.stub',
+  },
 })