resora 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -124,27 +124,75 @@ type GenericBody<R extends NonCollectible | Collectible | ResourceData = Resourc
 //#endregion
 //#region src/types/config.d.ts
 interface Config {
+  /**
+   * @description The directory where resource definitions are located.
+   * @default 'resources'
+   */
   resourcesDir: string;
+  /**
+   * @description The directory where stub files are located.
+   * @default 'node_modules/resora/stubs'
+   */
   stubsDir: string;
+  /**
+   * @description The file names of the various stub templates used for generating resources and configuration.
+   * Each property corresponds to a specific type of stub:
+   * - config: The stub file for generating the default configuration file.
+   * - resource: The stub file for generating a single resource.
+   * - collection: The stub file for generating a collection of resources.
+   * All properties are required and should be provided as strings representing the file names of the respective stubs.
+   */
   stubs: {
     config: string;
     resource: string;
     collection: string;
   };
+  /**
+   * @description The preferred case style for resource keys in the response.
+   * Can be set to a preset string ('camel', 'snake', 'pascal', 'kebab') or a custom transformer function.
+   * @default 'camel'
+   */
   preferredCase: CaseStyle;
+  /**
+   * @description An array or object specifying which additional data to include in paginated responses.
+   * Can include 'meta', 'links', and/or 'cursor'. If an object is provided, the keys can be customized to specify the property names for each type of extra data in the response.
+   * @default ['meta', 'links']
+   */
   paginatedExtras: ('meta' | 'links' | 'cursor')[] | {
     meta?: string | undefined;
     links?: string | undefined;
     cursor?: string | undefined;
   };
+  /**
+   * @description The base URL to use for generating pagination links in responses.
+   * @default 'https://localhost'
+   */
   baseUrl: string;
+  /**
+   * @description The query parameter name to use for the page number in paginated requests.
+   * @default 'page'
+   */
   pageName: string;
+  /**
+   * @description An object specifying the keys to use for pagination links in the response. Each property corresponds to a specific pagination link:
+   * - first: The key for the link to the first page of results.
+   * - last: The key for the link to the last page of results.
+   * - prev: The key for the link to the previous page of results.
+   * - next: The key for the link to the next page of results.
+   * All properties are optional and can be customized to specify the desired keys for pagination links in the response.
+   */
   paginatedLinks: {
     first?: string | undefined;
     last?: string | undefined;
     prev?: string | undefined;
     next?: string | undefined;
   };
+  /**
+   * @description An object specifying the keys to use for pagination metadata in the response. Each property corresponds to a specific piece of pagination information:
+   * - to: The key for the index of the last item in the current page of results.
+   * - from: The key for the index of the first item in the current page of results.
+   * - links: The key for any additional pagination links included in the response.
+   */
   paginatedMeta: {
     to?: string | undefined;
     from?: string | undefined;
@@ -155,13 +203,63 @@ interface Config {
     last_page?: string | undefined;
     current_page?: string | undefined;
   };
+  /**
+   * @description An object specifying the keys to use for cursor pagination metadata in the response. Each property corresponds to a specific piece of cursor pagination information:
+   * - previous: The key for the cursor value that points to the previous page of results.
+   * - next: The key for the cursor value that points to the next page of results.
+   * Both properties are optional and can be customized to specify the desired keys for cursor pagination metadata in the response.
+   */
   cursorMeta: {
     previous?: string | undefined;
     next?: string | undefined;
   };
+  /**
+   * @description An object specifying the structure of the response body for resources. It includes a rootKey property that defines the key under which the resource data will be nested in the response. The rootKey is a string that represents the name of this key in the response body.
+   */
   responseStructure: ResponseStructureConfig;
+  /**
+   * @description An optional array of additional command classes to be registered with the framework. Each command class should extend the base Command class provided by the '@h3ravel/musket' package. This allows users to easily add custom commands to their application by including them in this array when defining the configuration.
+   */
   extraCommands?: typeof Command<any>[];
 }
+interface ResoraConfig extends Partial<Omit<Config, 'stubs' | 'cursorMeta' | 'paginatedMeta' | 'paginatedLinks' | 'responseStructure'>> {
+  /**
+   * @description The file names of the various stub templates used for generating resources and configuration.
+   * Each property corresponds to a specific type of stub:
+   * - config: The stub file for generating the default configuration file.
+   * - resource: The stub file for generating a single resource.
+   * - collection: The stub file for generating a collection of resources.
+   * All properties are required and should be provided as strings representing the file names of the respective stubs.
+   */
+  stubs?: Partial<Config['stubs']>;
+  /**
+   * @description An object specifying the keys to use for cursor pagination metadata in the response. Each property corresponds to a specific piece of cursor pagination information:
+   * - previous: The key for the cursor value that points to the previous page of results.
+   * - next: The key for the cursor value that points to the next page of results.
+   * Both properties are optional and can be customized to specify the desired keys for cursor pagination metadata in the response.
+   */
+  cursorMeta?: Partial<Config['cursorMeta']>;
+  /**
+   * @description An object specifying the keys to use for pagination metadata in the response. Each property corresponds to a specific piece of pagination information:
+   * - to: The key for the index of the last item in the current page of results.
+   * - from: The key for the index of the first item in the current page of results.
+   * - links: The key for any additional pagination links included in the response.
+   */
+  paginatedMeta?: Partial<Config['paginatedMeta']>;
+  /**
+   * @description An object specifying the keys to use for pagination links in the response. Each property corresponds to a specific pagination link:
+   * - first: The key for the link to the first page of results.
+   * - last: The key for the link to the last page of results.
+   * - prev: The key for the link to the previous page of results.
+   * - next: The key for the link to the next page of results.
+   * All properties are optional and can be customized to specify the desired keys for pagination links in the response.
+   */
+  paginatedLinks?: Partial<Config['paginatedLinks']>;
+  /**
+   * @description An object specifying the structure of the response body for resources. It includes a rootKey property that defines the key under which the resource data will be nested in the response. The rootKey is a string that represents the name of this key in the response body.
+   */
+  responseStructure?: Partial<Config['responseStructure']>;
+}
 //#endregion
 //#region src/cli/CliApp.d.ts
 declare class CliApp {
@@ -644,44 +742,168 @@ declare class GenericResource<R extends NonCollectible | Collectible | ResourceD
 }
 //#endregion
 //#region src/utilities/case.d.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
+ */
 declare const splitWords: (str: string) => string[];
+/**
+ * Transforms a string to camelCase.
+ *
+ * @param str
+ * @returns
+ */
 declare const toCamelCase: (str: string) => string;
+/**
+ * Transforms a string to snake_case.
+ *
+ * @param str
+ * @returns
+ */
 declare const toSnakeCase: (str: string) => string;
+/**
+ * Transforms a string to PascalCase.
+ *
+ * @param str
+ * @returns
+ */
 declare const toPascalCase: (str: string) => string;
+/**
+ * Transforms a string to kebab-case.
+ *
+ * @param str
+ * @returns
+ */
 declare const toKebabCase: (str: string) => string;
+/**
+ * Retrieves the appropriate case transformation function based on the provided style.
+ *
+ * @param style
+ * @returns
+ */
 declare const getCaseTransformer: (style: CaseStyle) => ((key: string) => string);
+/**
+ * Transforms the keys of an object (including nested objects and arrays) using
+ * the provided transformer function.
+ *
+ * @param obj
+ * @param transformer
+ * @returns
+ */
 declare const transformKeys: (obj: any, transformer: (key: string) => string) => any;
 //#endregion
 //#region src/utilities/conditional.d.ts
 declare const CONDITIONAL_ATTRIBUTE_MISSING: unique symbol;
+/**
+ * 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.
+ */
 declare const resolveWhen: <T>(condition: any, value: T | (() => T)) => T | typeof CONDITIONAL_ATTRIBUTE_MISSING;
+/**
+ * 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.
+ */
 declare const resolveWhenNotNull: <T>(value: T | null | undefined) => T | typeof CONDITIONAL_ATTRIBUTE_MISSING;
+/**
+ * Conditionally merges object attributes based on a condition.
+ *
+ * @param condition
+ * @param value
+ * @returns
+ */
 declare const resolveMergeWhen: <T extends Record<string, any>>(condition: any, value: T | (() => T)) => Partial<T>;
+/**
+ *  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.
+ */
 declare const sanitizeConditionalAttributes: (value: any) => any;
 //#endregion
 //#region src/utilities/config.d.ts
 declare const getDefaultConfig: () => Config;
-declare const defineConfig: (userConfig?: Partial<Omit<Config, "stubs">> & {
-  stubs?: Partial<Config["stubs"]>;
-}) => Config;
+/**
+ * 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
+ */
+declare const defineConfig: (config: ResoraConfig) => Config;
 //#endregion
 //#region src/utilities/metadata.d.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.
+ */
 declare const resolveWithHookMetadata: (instance: any, baseWithMethod: (...args: any[]) => any) => MetaData | undefined;
 //#endregion
 //#region src/utilities/objects.d.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.
+ */
 declare const isPlainObject: (value: any) => value is Record<string, any>;
+/**
+ * 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.
+ */
 declare const appendRootProperties: (body: any, extra?: Record<string, any> | undefined, rootKey?: string) => any;
+/**
+ * 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
+ */
 declare const mergeMetadata: (base?: Record<string, any> | undefined, incoming?: Record<string, any> | undefined) => Record<string, any> | undefined;
 //#endregion
 //#region src/utilities/pagination.d.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.
+ */
 declare const getPaginationExtraKeys: () => {
   metaKey?: string;
   linksKey?: string;
   cursorKey?: string;
 };
+/**
+ * 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.
+ */
 declare const buildPaginationExtras: (resource: any) => Record<string, any>;
 //#endregion
 //#region src/utilities/response.d.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.
+ */
 declare const buildResponseEnvelope: ({
   payload,
   meta,
@@ -700,28 +922,177 @@ declare const buildResponseEnvelope: ({
   context: Omit<ResponseFactoryContext, "rootKey" | "meta">;
 }) => Record<string, any>;
 //#endregion
+//#region src/utilities/runtime-config.d.ts
+/**
+ * Resets the runtime configuration state for testing purposes.
+ *
+ * @returns
+ */
+declare const resetRuntimeConfigForTests: () => void;
+/**
+ * Applies the provided configuration to the global state of the application.
+ *
+ * @param config The complete configuration object to apply.
+ */
+declare const applyRuntimeConfig: (config: Config) => void;
+/**
+ * Loads the runtime configuration by searching for configuration files in the current working directory.
+ *
+ * @returns
+ */
+declare const loadRuntimeConfig: () => Promise<void>;
+//#endregion
 //#region src/utilities/state.d.ts
+/**
+ * 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.
+ */
 declare const setGlobalCase: (style: CaseStyle | undefined) => void;
+/**
+ * Retrieves the global case style for response keys, which is used
+ * to determine how keys in responses should be formatted.
+ *
+ * @returns
+ */
 declare const getGlobalCase: () => CaseStyle | undefined;
+/**
+ * Sets the global response structure configuration, which defines how
+ * responses should be structured across the application.
+ *
+ * @param config The response structure configuration object.
+ */
 declare const setGlobalResponseStructure: (config: ResponseStructureConfig | undefined) => void;
+/**
+ * Retrieves the global response structure configuration, which
+ * defines how  responses should be structured across the application.
+ *
+ * @returns
+ */
 declare const getGlobalResponseStructure: () => ResponseStructureConfig | undefined;
+/**
+ * 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.
+ */
 declare const setGlobalResponseRootKey: (rootKey: string | undefined) => void;
+/**
+ * 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.
+ */
 declare const setGlobalResponseWrap: (wrap: boolean | undefined) => void;
+/**
+ * Retrieves the global response wrap option, which indicates whether responses
+ * should be wrapped in a root key or returned unwrapped when possible.
+ *
+ * @returns
+ */
 declare const getGlobalResponseWrap: () => boolean | undefined;
+/**
+ * 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
+ */
 declare const getGlobalResponseRootKey: () => string | undefined;
+/**
+ * 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.
+ */
 declare const setGlobalResponseFactory: (factory: ResponseFactory | undefined) => void;
+/**
+ * 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
+ */
 declare const getGlobalResponseFactory: () => ResponseFactory | undefined;
+/**
+ * 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.
+ */
 declare const setGlobalPaginatedExtras: (extras: Config["paginatedExtras"]) => void;
+/**
+ * Retrieves the global paginated extras configuration, which defines the keys to use for pagination metadata, links, and cursor information in paginated responses.
+ *
+ * @returns
+ */
 declare const getGlobalPaginatedExtras: () => Config["paginatedExtras"];
+/**
+ * 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.
+ */
 declare const setGlobalPaginatedLinks: (links: Config["paginatedLinks"]) => void;
+/**
+ * Retrieves the global paginated links configuration, which defines the keys to use for pagination links (first, last, prev, next) in paginated responses.
+ *
+ * @returns
+ */
 declare const getGlobalPaginatedLinks: () => Config["paginatedLinks"];
+/**
+ * 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.
+ */
 declare const setGlobalBaseUrl: (baseUrl: Config["baseUrl"]) => void;
+/**
+ * Retrieves the global base URL, which is used for generating pagination links in responses.
+ *
+ * @returns
+ */
 declare const getGlobalBaseUrl: () => Config["baseUrl"];
+/**
+ * Sets the global page name, which is the query parameter name used for the page number in paginated requests and link generation.
+ *
+ * @param pageName
+ */
 declare const setGlobalPageName: (pageName: Config["pageName"]) => void;
+/**
+ * Retrieves the global page name, which is the query parameter name
+ * used for the page number in paginated requests and link generation.
+ *
+ * @returns
+ */
 declare const getGlobalPageName: () => Config["pageName"];
+/**
+ * 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.
+ */
 declare const setGlobalPaginatedMeta: (meta: Config["paginatedMeta"]) => void;
+/**
+ * Retrieves the keys to use for pagination extras (meta, links, cursor) based
+ * on the global configuration.
+ *
+ * @returns The global pagination metadata configuration.
+ */
 declare const getGlobalPaginatedMeta: () => Config["paginatedMeta"];
+/**
+ * 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.
+ */
 declare const setGlobalCursorMeta: (meta: Config["cursorMeta"]) => void;
+/**
+ * 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.
+ */
 declare const getGlobalCursorMeta: () => Config["cursorMeta"];
 //#endregion
-export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponseStructureConfig, 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, CaseStyle, CliApp, Collectible, CollectionBody, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, ResoraConfig, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponseStructureConfig, 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 };