resora 0.2.18 → 1.0.0

package/dist/index.d.cts

@@ -298,6 +298,47 @@ interface ResoraConfig extends Partial<Omit<Config, 'stubs' | 'cursorMeta' | 'pa
   responseStructure?: Partial<Config['responseStructure']>;
 }
 //#endregion
+//#region src/types/plugin.d.ts
+type ResoraPluginUtility = (...args: any[]) => unknown;
+interface ResoraPluginApi {
+  runWithCtx: <T>(ctx: unknown, callback: () => T) => T;
+  setCtx: (ctx: unknown) => void;
+  getCtx: () => unknown;
+  registerUtility: (name: string, utility: ResoraPluginUtility) => ResoraPluginUtility;
+  getUtility: <T extends ResoraPluginUtility = ResoraPluginUtility>(name: string) => T | undefined;
+  getRegisteredPlugins: () => ResoraPlugin[];
+}
+interface SerializePluginEvent<TBody = any, TResource = any> {
+  serializer: unknown;
+  serializerType: ResponseKind;
+  resource: TResource;
+  body: TBody;
+}
+interface ResponsePluginEvent<TBody = any> {
+  serializer: unknown;
+  serializerType: ResponseKind;
+  rawResponse?: unknown;
+  response?: unknown;
+  body: TBody;
+}
+interface SendPluginEvent<TBody = any> {
+  response: unknown;
+  rawResponse: unknown;
+  body: TBody;
+  status: number;
+  headers: Record<string, string>;
+}
+interface ResoraPlugin {
+  name: string;
+  setup?: (api: ResoraPluginApi) => void;
+  beforeSerialize?: (event: SerializePluginEvent, api: ResoraPluginApi) => void;
+  afterSerialize?: (event: SerializePluginEvent, api: ResoraPluginApi) => void;
+  beforeResponse?: (event: ResponsePluginEvent, api: ResoraPluginApi) => void;
+  afterResponse?: (event: ResponsePluginEvent, api: ResoraPluginApi) => void;
+  beforeSend?: (event: SendPluginEvent, api: ResoraPluginApi) => void;
+  afterSend?: (event: SendPluginEvent, api: ResoraPluginApi) => void;
+}
+//#endregion
 //#region src/cli/CliApp.d.ts
 declare class CliApp {
   command: Command;
@@ -529,6 +570,43 @@ declare abstract class BaseSerializer<TResource = any> {
   protected abstract resolveCurrentRootKey(): string;
   protected abstract applyMetaToBody(meta: MetaData, rootKey: string): void;
   protected abstract getResourceForMeta(): TResource;
+  protected abstract getSerializerType(): ResponseKind;
+  protected abstract setBody(body: any): this;
+  /**
+   * Apply registered plugins for the serialization process, allowing plugins to
+   * modify the response body and metadata before the response is sent.
+   *
+   * @param body
+   * @returns
+   */
+  protected applySerializePlugins<TBody>(body: TBody): TBody;
+  /**
+   * Apply registered plugins for the response process, allowing plugins to modify the
+   * response body, headers, and status before the response is sent.
+   *
+   * @param input
+   * @returns
+   */
+  protected applyResponsePlugins<TBody, TRawResponse, TServerResponse>(input: {
+    body: TBody;
+    rawResponse?: TRawResponse;
+    response?: TServerResponse;
+  }): TBody;
+  /**
+   * Resolve the raw response object from the provided response or the current
+   * context, allowing plugins to access and modify the raw response before it is sent.
+   *
+   * @param response
+   * @returns
+   */
+  protected resolveRawResponse<TRawResponse>(response?: TRawResponse): TRawResponse | undefined;
+  /**
+   * Dispatch a body to a raw response object when it exposes a send() transport method.
+   *
+   * @param raw
+   * @param body
+   */
+  protected sendRawResponseBody<TBody>(raw: unknown, body: TBody): void;
   /**
    * Add additional metadata to the response. If called without arguments.
    *
@@ -693,6 +771,7 @@ declare class ResourceCollection<R extends ResourceData[] | Collectible | Collec
    * @returns
    */
   protected getResourceForMeta(): R;
+  protected getSerializerType(): "collection";
   /**
    * Get the appropriate key for the response payload based on the current response
    * structure configuration.
@@ -747,8 +826,8 @@ declare class ResourceCollection<R extends ResourceData[] | Collectible | Collec
   /**
    * Promise-like then method to allow chaining with async/await or .then() syntax
    *
-   * @param onfulfilled  Callback to handle the fulfilled state of the promise, receiving the response body
-   * @param onrejected  Callback to handle the rejected state of the promise, receiving the error reason
+   * @param onfulfilled  Callback to handle the fulfilled state of the promise
+   * @param onrejected  Callback to handle the rejected state of the promise
    * @returns A promise that resolves to the result of the onfulfilled or onrejected callback
    */
   then<TResult1 = CollectionBody<R>, TResult2 = never>(onfulfilled?: ((value: CollectionBody<R>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
@@ -815,6 +894,7 @@ declare class Resource<R extends ResourceData | NonCollectible = ResourceData> e
   protected resolveCurrentRootKey(): string;
   protected applyMetaToBody(meta: MetaData, rootKey: string): void;
   protected getResourceForMeta(): R;
+  protected getSerializerType(): "resource";
   private getPayloadKey;
   /**
    * Convert resource to JSON response format
@@ -935,6 +1015,7 @@ declare class GenericResource<R extends NonCollectible | Collectible | Collectio
    * @returns
    */
   protected getResourceForMeta(): R;
+  protected getSerializerType(): "generic";
   private getPayloadKey;
   /**
    * Convert resource to JSON response format
@@ -1004,6 +1085,24 @@ declare class GenericResource<R extends NonCollectible | Collectible | Collectio
   finally(onfinally?: (() => void) | null): Promise<unknown>;
 }
 //#endregion
+//#region src/plugins.d.ts
+type HookEventMap = {
+  beforeSerialize: SerializePluginEvent;
+  afterSerialize: SerializePluginEvent;
+  beforeResponse: ResponsePluginEvent;
+  afterResponse: ResponsePluginEvent;
+  beforeSend: SendPluginEvent;
+  afterSend: SendPluginEvent;
+};
+type HookName = keyof HookEventMap;
+declare const getRegisteredPlugins: () => ResoraPlugin[];
+declare const registerUtility: (name: string, utility: ResoraPluginUtility) => ResoraPluginUtility;
+declare const getUtility: <T extends ResoraPluginUtility = ResoraPluginUtility>(name: string) => T | undefined;
+declare const definePlugin: <T extends ResoraPlugin>(plugin: T) => T;
+declare const registerPlugin: (plugins: ResoraPlugin | ResoraPlugin[]) => ResoraPlugin[];
+declare const runPluginHook: <THook extends HookName>(hook: THook, event: HookEventMap[THook]) => HookEventMap[THook];
+declare const resetPluginsForTests: () => void;
+//#endregion
 //#region src/utilities/case.d.ts
 /**
  * Splits a string into words based on common delimiters and capitalization patterns.
@@ -1436,6 +1535,8 @@ declare const setRequestUrl: (url: string | undefined) => void;
  * @returns The current request URL, or undefined if not set.
  */
 declare const getRequestUrl: () => string | undefined;
+declare const runWithCtx: <T>(ctx: unknown, callback: () => T) => T;
+declare const getCtx: () => unknown;
 /**
  * Extracts the request URL pathname (with query string) from an HTTP context.
  *
@@ -1472,4 +1573,4 @@ declare const extractResponseFromCtx: (ctx: unknown) => any | undefined;
  */
 declare const setCtx: (ctx: unknown) => void;
 //#endregion
-export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponseStructureConfig, ServerResponse, appendRootProperties, applyRuntimeConfig, buildPaginationExtras, buildResponseEnvelope, createArkormCurrentPageResolver, defineConfig, extractRequestUrl, extractResponseFromCtx, getCaseTransformer, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, getRequestUrl, hasPaginationLink, isArkormLikeCollection, isArkormLikeModel, isPlainObject, loadRuntimeConfig, mergeMetadata, normalizeSerializableData, resetRuntimeConfigForTests, resolveCurrentPage, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, sanitizeConditionalAttributes, setCtx, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, setRequestUrl, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };
+export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, ResoraPlugin, ResoraPluginApi, ResoraPluginUtility, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponsePluginEvent, ResponseStructureConfig, SendPluginEvent, SerializePluginEvent, ServerResponse, appendRootProperties, applyRuntimeConfig, buildPaginationExtras, buildResponseEnvelope, createArkormCurrentPageResolver, defineConfig, definePlugin, extractRequestUrl, extractResponseFromCtx, getCaseTransformer, getCtx, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, getRegisteredPlugins, getRequestUrl, getUtility, hasPaginationLink, isArkormLikeCollection, isArkormLikeModel, isPlainObject, loadRuntimeConfig, mergeMetadata, normalizeSerializableData, registerPlugin, registerUtility, resetPluginsForTests, resetRuntimeConfigForTests, resolveCurrentPage, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, runPluginHook, runWithCtx, sanitizeConditionalAttributes, setCtx, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, setRequestUrl, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };

package/dist/index.d.mts

@@ -298,6 +298,47 @@ interface ResoraConfig extends Partial<Omit<Config, 'stubs' | 'cursorMeta' | 'pa
   responseStructure?: Partial<Config['responseStructure']>;
 }
 //#endregion
+//#region src/types/plugin.d.ts
+type ResoraPluginUtility = (...args: any[]) => unknown;
+interface ResoraPluginApi {
+  runWithCtx: <T>(ctx: unknown, callback: () => T) => T;
+  setCtx: (ctx: unknown) => void;
+  getCtx: () => unknown;
+  registerUtility: (name: string, utility: ResoraPluginUtility) => ResoraPluginUtility;
+  getUtility: <T extends ResoraPluginUtility = ResoraPluginUtility>(name: string) => T | undefined;
+  getRegisteredPlugins: () => ResoraPlugin[];
+}
+interface SerializePluginEvent<TBody = any, TResource = any> {
+  serializer: unknown;
+  serializerType: ResponseKind;
+  resource: TResource;
+  body: TBody;
+}
+interface ResponsePluginEvent<TBody = any> {
+  serializer: unknown;
+  serializerType: ResponseKind;
+  rawResponse?: unknown;
+  response?: unknown;
+  body: TBody;
+}
+interface SendPluginEvent<TBody = any> {
+  response: unknown;
+  rawResponse: unknown;
+  body: TBody;
+  status: number;
+  headers: Record<string, string>;
+}
+interface ResoraPlugin {
+  name: string;
+  setup?: (api: ResoraPluginApi) => void;
+  beforeSerialize?: (event: SerializePluginEvent, api: ResoraPluginApi) => void;
+  afterSerialize?: (event: SerializePluginEvent, api: ResoraPluginApi) => void;
+  beforeResponse?: (event: ResponsePluginEvent, api: ResoraPluginApi) => void;
+  afterResponse?: (event: ResponsePluginEvent, api: ResoraPluginApi) => void;
+  beforeSend?: (event: SendPluginEvent, api: ResoraPluginApi) => void;
+  afterSend?: (event: SendPluginEvent, api: ResoraPluginApi) => void;
+}
+//#endregion
 //#region src/cli/CliApp.d.ts
 declare class CliApp {
   command: Command;
@@ -529,6 +570,43 @@ declare abstract class BaseSerializer<TResource = any> {
   protected abstract resolveCurrentRootKey(): string;
   protected abstract applyMetaToBody(meta: MetaData, rootKey: string): void;
   protected abstract getResourceForMeta(): TResource;
+  protected abstract getSerializerType(): ResponseKind;
+  protected abstract setBody(body: any): this;
+  /**
+   * Apply registered plugins for the serialization process, allowing plugins to
+   * modify the response body and metadata before the response is sent.
+   *
+   * @param body
+   * @returns
+   */
+  protected applySerializePlugins<TBody>(body: TBody): TBody;
+  /**
+   * Apply registered plugins for the response process, allowing plugins to modify the
+   * response body, headers, and status before the response is sent.
+   *
+   * @param input
+   * @returns
+   */
+  protected applyResponsePlugins<TBody, TRawResponse, TServerResponse>(input: {
+    body: TBody;
+    rawResponse?: TRawResponse;
+    response?: TServerResponse;
+  }): TBody;
+  /**
+   * Resolve the raw response object from the provided response or the current
+   * context, allowing plugins to access and modify the raw response before it is sent.
+   *
+   * @param response
+   * @returns
+   */
+  protected resolveRawResponse<TRawResponse>(response?: TRawResponse): TRawResponse | undefined;
+  /**
+   * Dispatch a body to a raw response object when it exposes a send() transport method.
+   *
+   * @param raw
+   * @param body
+   */
+  protected sendRawResponseBody<TBody>(raw: unknown, body: TBody): void;
   /**
    * Add additional metadata to the response. If called without arguments.
    *
@@ -693,6 +771,7 @@ declare class ResourceCollection<R extends ResourceData[] | Collectible | Collec
    * @returns
    */
   protected getResourceForMeta(): R;
+  protected getSerializerType(): "collection";
   /**
    * Get the appropriate key for the response payload based on the current response
    * structure configuration.
@@ -747,8 +826,8 @@ declare class ResourceCollection<R extends ResourceData[] | Collectible | Collec
   /**
    * Promise-like then method to allow chaining with async/await or .then() syntax
    *
-   * @param onfulfilled  Callback to handle the fulfilled state of the promise, receiving the response body
-   * @param onrejected  Callback to handle the rejected state of the promise, receiving the error reason
+   * @param onfulfilled  Callback to handle the fulfilled state of the promise
+   * @param onrejected  Callback to handle the rejected state of the promise
    * @returns A promise that resolves to the result of the onfulfilled or onrejected callback
    */
   then<TResult1 = CollectionBody<R>, TResult2 = never>(onfulfilled?: ((value: CollectionBody<R>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
@@ -815,6 +894,7 @@ declare class Resource<R extends ResourceData | NonCollectible = ResourceData> e
   protected resolveCurrentRootKey(): string;
   protected applyMetaToBody(meta: MetaData, rootKey: string): void;
   protected getResourceForMeta(): R;
+  protected getSerializerType(): "resource";
   private getPayloadKey;
   /**
    * Convert resource to JSON response format
@@ -935,6 +1015,7 @@ declare class GenericResource<R extends NonCollectible | Collectible | Collectio
    * @returns
    */
   protected getResourceForMeta(): R;
+  protected getSerializerType(): "generic";
   private getPayloadKey;
   /**
    * Convert resource to JSON response format
@@ -1004,6 +1085,24 @@ declare class GenericResource<R extends NonCollectible | Collectible | Collectio
   finally(onfinally?: (() => void) | null): Promise<unknown>;
 }
 //#endregion
+//#region src/plugins.d.ts
+type HookEventMap = {
+  beforeSerialize: SerializePluginEvent;
+  afterSerialize: SerializePluginEvent;
+  beforeResponse: ResponsePluginEvent;
+  afterResponse: ResponsePluginEvent;
+  beforeSend: SendPluginEvent;
+  afterSend: SendPluginEvent;
+};
+type HookName = keyof HookEventMap;
+declare const getRegisteredPlugins: () => ResoraPlugin[];
+declare const registerUtility: (name: string, utility: ResoraPluginUtility) => ResoraPluginUtility;
+declare const getUtility: <T extends ResoraPluginUtility = ResoraPluginUtility>(name: string) => T | undefined;
+declare const definePlugin: <T extends ResoraPlugin>(plugin: T) => T;
+declare const registerPlugin: (plugins: ResoraPlugin | ResoraPlugin[]) => ResoraPlugin[];
+declare const runPluginHook: <THook extends HookName>(hook: THook, event: HookEventMap[THook]) => HookEventMap[THook];
+declare const resetPluginsForTests: () => void;
+//#endregion
 //#region src/utilities/case.d.ts
 /**
  * Splits a string into words based on common delimiters and capitalization patterns.
@@ -1436,6 +1535,8 @@ declare const setRequestUrl: (url: string | undefined) => void;
  * @returns The current request URL, or undefined if not set.
  */
 declare const getRequestUrl: () => string | undefined;
+declare const runWithCtx: <T>(ctx: unknown, callback: () => T) => T;
+declare const getCtx: () => unknown;
 /**
  * Extracts the request URL pathname (with query string) from an HTTP context.
  *
@@ -1472,4 +1573,4 @@ declare const extractResponseFromCtx: (ctx: unknown) => any | undefined;
  */
 declare const setCtx: (ctx: unknown) => void;
 //#endregion
-export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponseStructureConfig, ServerResponse, appendRootProperties, applyRuntimeConfig, buildPaginationExtras, buildResponseEnvelope, createArkormCurrentPageResolver, defineConfig, extractRequestUrl, extractResponseFromCtx, getCaseTransformer, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, getRequestUrl, hasPaginationLink, isArkormLikeCollection, isArkormLikeModel, isPlainObject, loadRuntimeConfig, mergeMetadata, normalizeSerializableData, resetRuntimeConfigForTests, resolveCurrentPage, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, sanitizeConditionalAttributes, setCtx, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, setRequestUrl, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };
+export { ApiResource, CONDITIONAL_ATTRIBUTE_MISSING, CaseStyle, CliApp, Collectible, CollectionBody, CollectionLike, Config, Cursor, GenericBody, GenericResource, InitCommand, MakeResource, MetaData, NonCollectible, PaginatedMetaData, Pagination, PaginatorLike, ResoraConfig, ResoraPlugin, ResoraPluginApi, ResoraPluginUtility, Resource, ResourceBody, ResourceCollection, ResourceData, ResourceDef, ResourceLevelConfig, ResponseData, ResponseDataCollection, ResponseFactory, ResponseFactoryContext, ResponseKind, ResponsePluginEvent, ResponseStructureConfig, SendPluginEvent, SerializePluginEvent, ServerResponse, appendRootProperties, applyRuntimeConfig, buildPaginationExtras, buildResponseEnvelope, createArkormCurrentPageResolver, defineConfig, definePlugin, extractRequestUrl, extractResponseFromCtx, getCaseTransformer, getCtx, getDefaultConfig, getGlobalBaseUrl, getGlobalCase, getGlobalCursorMeta, getGlobalPageName, getGlobalPaginatedExtras, getGlobalPaginatedLinks, getGlobalPaginatedMeta, getGlobalResponseFactory, getGlobalResponseRootKey, getGlobalResponseStructure, getGlobalResponseWrap, getPaginationExtraKeys, getRegisteredPlugins, getRequestUrl, getUtility, hasPaginationLink, isArkormLikeCollection, isArkormLikeModel, isPlainObject, loadRuntimeConfig, mergeMetadata, normalizeSerializableData, registerPlugin, registerUtility, resetPluginsForTests, resetRuntimeConfigForTests, resolveCurrentPage, resolveMergeWhen, resolveWhen, resolveWhenNotNull, resolveWithHookMetadata, runPluginHook, runWithCtx, sanitizeConditionalAttributes, setCtx, setGlobalBaseUrl, setGlobalCase, setGlobalCursorMeta, setGlobalPageName, setGlobalPaginatedExtras, setGlobalPaginatedLinks, setGlobalPaginatedMeta, setGlobalResponseFactory, setGlobalResponseRootKey, setGlobalResponseStructure, setGlobalResponseWrap, setRequestUrl, splitWords, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, transformKeys };