resora 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,328 @@
+import { H3Event } from "h3";
+import { Response } from "express";
+
+//#region src/ApiResource.d.ts
+/**
+ * ApiResource function to return the Resource instance
+ *
+ * @param instance Resource instance
+ * @returns Resource instance
+ */
+declare function ApiResource<R extends Resource>(instance: Resource<R>): Resource<R>;
+//#endregion
+//#region src/types.d.ts
+interface MetaData {
+  [key: string]: any;
+}
+interface ResourceData {
+  [key: string]: any;
+}
+interface Resource$1 extends ResourceData {
+  cursor?: Cursor | undefined;
+  pagination?: Pagination | undefined;
+}
+interface NonCollectible {
+  data: ResourceData;
+}
+interface Collectible {
+  data: ResourceData[];
+  cursor?: Cursor | undefined;
+  pagination?: Pagination | undefined;
+}
+interface ResponseData<R extends ResourceData = any> extends Resource$1 {
+  data: R;
+  meta?: MetaData | undefined;
+}
+type PaginatedMetaData<R extends Collectible = Collectible> = MetaData & Omit<R, 'data'>;
+interface ResponseDataCollection<R extends Collectible | undefined = undefined> extends ResourceData {
+  data: R extends Collectible ? R['data'] : R;
+  meta?: R extends Collectible ? PaginatedMetaData<R> | undefined : undefined;
+}
+/**
+ * @description A type that represents the body of a response for a collection of resources.
+ * It can be either an array of ResourceData objects or a Collectible object, which contains an
+ * array of ResourceData objects. The type also includes the meta property, which is optional
+ * and can contain any additional metadata related to the response.
+ * @example
+ * const collectionResponse: CollectionBody = {
+ *   data: [
+ *     { id: 1, name: 'Resource 1' },
+ *     { id: 2, name: 'Resource 2' }
+ *   ],
+ *   meta: {
+ *     pagination: {
+ *       currentPage: 1,
+ *       total: 2
+ *     }
+ *   }
+ * };
+ */
+type CollectionBody<R extends ResourceData[] | Collectible = ResourceData[]> = ResponseDataCollection<R extends Collectible ? R : {
+  data: R;
+}>;
+/**
+ * @description A type that represents the body of a response for a single resource.
+ * It can be either a ResourceData object or a NonCollectible object, which contains a
+ * ResourceData object. The type also includes the meta property, which is optional and can
+ * contain any additional metadata related to the response.
+ * @example
+ * const resourceResponse: ResourceBody = {
+ *   data: {
+ *     id: 1,
+ *     name: 'Resource Name',
+ *     description: 'Resource Description'
+ *   },
+ *   meta: {
+ *     timestamp: '2024-06-01T12:00:00Z'
+ *   }
+ * };
+ */
+type ResourceBody<R extends ResourceData | NonCollectible = ResourceData> = ResponseData<R extends NonCollectible ? R : {
+  data: R;
+}>;
+/**
+ * @description A type that represents the pagination information for a collection of resources. It includes properties such as currentPage, from, to, perPage, total, firstPage, lastPage, prevPage, and nextPage. All properties are optional and can be undefined if not applicable.
+ * @example
+ * const paginationInfo: Pagination = {
+ *   currentPage: 1,
+ *   from: 1,
+ *   to: 10,
+ *   perPage: 10,
+ *   total: 100,
+ *   firstPage: 1,
+ *   lastPage: 10,
+ *   prevPage: null,
+ *   nextPage: 2
+ * };
+ */
+interface Pagination {
+  currentPage?: number | undefined;
+  from?: number | undefined;
+  to?: number | undefined;
+  perPage?: number | undefined;
+  total?: number | undefined;
+  firstPage?: number | undefined;
+  lastPage?: number | undefined;
+  prevPage?: number | undefined;
+  nextPage?: number | undefined;
+}
+/**
+ * @description A type that represents the cursor information for pagination. It includes properties such as before and after, which are optional and can be undefined if not applicable. The before property represents the cursor for the previous page, while the after property represents the cursor for the next page.
+ * @example
+ * const cursorInfo: Cursor = {
+ *   previous: 'cursor-for-previous-page',
+ *   next: 'cursor-for-next-page'
+ * };
+ */
+interface Cursor {
+  previous?: string | undefined;
+  next?: string | undefined;
+}
+//#endregion
+//#region src/ServerResponse.d.ts
+declare class ServerResponse<R extends NonCollectible | Collectible | ResourceData[] | ResourceData = ResourceData> {
+  #private;
+  private response;
+  private body;
+  private _status;
+  headers: Record<string, string>;
+  constructor(response: H3Event['res'], body: R);
+  constructor(response: Response, body: R);
+  /**
+   * Set the HTTP status code for the response
+   *
+   * @param status
+   * @returns The current ServerResponse instance
+   */
+  setStatusCode(status: number): this;
+  /**
+   * Get the current HTTP status code for the response
+   *
+   * @returns
+   */
+  status(): number;
+  /**
+   * Get the current HTTP status text for the response
+   *
+   * @returns
+   */
+  statusText(): string | undefined;
+  /**
+   * Set a cookie in the response header
+   *
+   * @param name The name of the cookie
+   * @param value The value of the cookie
+   * @param options Optional cookie attributes (e.g., path, domain, maxAge)
+   * @returns The current ServerResponse instance
+   */
+  setCookie(name: string, value: string, options?: Record<string, any>): this;
+  /**
+   * Convert the resource to a JSON response body
+   *
+   * @param headers Optional headers to add to the response
+   * @returns The current ServerResponse instance
+   */
+  setHeaders(headers: Record<string, string>): this;
+  /**
+   * Add a single header to the response
+   *
+   * @param key The name of the header
+   * @param value The value of the header
+   * @returns The current ServerResponse instance
+   */
+  header(key: string, value: string): this;
+  /**
+   * 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
+   * @returns A promise that resolves to the result of the onfulfilled or onrejected callback
+   */
+  then<TResult1 = R, TResult2 = never>(onfulfilled?: ((value: R) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+  /**
+   * Promise-like catch method to handle rejected state of the promise
+   *
+   * @param onrejected
+   * @returns
+   */
+  catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<R | TResult>;
+  /**
+   * Promise-like finally method to handle cleanup after promise is settled
+   *
+   * @param onfinally
+   * @returns
+   */
+  finally(onfinally?: (() => void) | null): Promise<void>;
+}
+//#endregion
+//#region src/ResourceCollection.d.ts
+/**
+ * ResourceCollection class to handle API resource transformation and response building for collections
+ */
+declare class ResourceCollection<R extends ResourceData[] | Collectible = ResourceData[], T extends ResourceData = any> {
+  private res?;
+  [key: string]: any;
+  body: CollectionBody<R>;
+  resource: R;
+  collects?: typeof Resource<T>;
+  private called;
+  constructor(rsc: R);
+  constructor(rsc: R, res: Response);
+  /**
+   * Get the original resource data
+   */
+  data(): (R extends Collectible ? R["data"][number] : R extends ResourceData[] ? R[number] : never)[];
+  /**
+   * Convert resource to JSON response format
+   *
+   * @returns
+   */
+  json(): this;
+  /**
+   * Flatten resource to return original data
+   *
+   * @returns
+   */
+  toArray(): (R extends Collectible ? R['data'][number] : R extends ResourceData[] ? R[number] : never)[];
+  /**
+   * Add additional properties to the response body
+   *
+   * @param extra  Additional properties to merge into the response body
+   * @returns
+   */
+  additional<X extends Record<string, any>>(extra: X): this;
+  response(): ServerResponse<CollectionBody<R>>;
+  response(res: H3Event['res']): ServerResponse<CollectionBody<R>>;
+  setCollects(collects: typeof Resource<T>): this;
+  /**
+   * 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
+   * @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>;
+  /**
+   * Promise-like catch method to handle rejected state of the promise
+   *
+   * @param onrejected
+   * @returns
+   */
+  catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<CollectionBody<R> | TResult>;
+  /**
+   * Promise-like finally method to handle cleanup after promise is settled
+   *
+   * @param onfinally
+   * @returns
+   */
+  finally(onfinally?: (() => void) | null): Promise<void>;
+}
+//#endregion
+//#region src/Resource.d.ts
+/**
+ * Resource class to handle API resource transformation and response building
+ */
+declare class Resource<R extends ResourceData | NonCollectible = ResourceData> {
+  private res?;
+  [key: string]: any;
+  body: ResourceBody<R>;
+  resource: R;
+  private called;
+  constructor(rsc: R, res?: Response | undefined);
+  /**
+   * Create a ResourceCollection from an array of resource data or a Collectible instance
+   *
+   * @param data
+   * @returns
+   */
+  static collection<C extends ResourceData[] | Collectible = ResourceData[], T extends ResourceData = any>(data: C): ResourceCollection<C, T>;
+  /**
+   * Get the original resource data
+   */
+  data(): R extends NonCollectible ? R["data"] : R;
+  /**
+   * Convert resource to JSON response format
+   *
+   * @returns
+   */
+  json(): this;
+  /**
+   * Flatten resource to array format (for collections) or return original data for single resources
+   *
+   * @returns
+   */
+  toArray(): R extends NonCollectible ? R['data'] : R;
+  /**
+   * Add additional properties to the response body
+   *
+   * @param extra  Additional properties to merge into the response body
+   * @returns
+   */
+  additional<X extends Record<string, any>>(extra: X): this;
+  response(): ServerResponse<ResourceBody<R>>;
+  response(res: H3Event['res']): ServerResponse<ResourceBody<R>>;
+  /**
+   * 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
+   * @returns A promise that resolves to the result of the onfulfilled or onrejected callback
+   */
+  then<TResult1 = ResourceBody<R>, TResult2 = never>(onfulfilled?: ((value: ResourceBody<R>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+  /**
+   * Promise-like catch method to handle rejected state of the promise
+   *
+   * @param onrejected
+   * @returns
+   */
+  catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<ResourceBody<R> | TResult>;
+  /**
+   * Promise-like finally method to handle cleanup after promise is settled
+   *
+   * @param onfinally
+   * @returns
+   */
+  finally(onfinally?: (() => void) | null): Promise<void>;
+}
+//#endregion
+export { ApiResource, Resource };

package/dist/index.d.mts

@@ -0,0 +1,328 @@
+import { H3Event } from "h3";
+import { Response } from "express";
+
+//#region src/ApiResource.d.ts
+/**
+ * ApiResource function to return the Resource instance
+ *
+ * @param instance Resource instance
+ * @returns Resource instance
+ */
+declare function ApiResource<R extends Resource>(instance: Resource<R>): Resource<R>;
+//#endregion
+//#region src/types.d.ts
+interface MetaData {
+  [key: string]: any;
+}
+interface ResourceData {
+  [key: string]: any;
+}
+interface Resource$1 extends ResourceData {
+  cursor?: Cursor | undefined;
+  pagination?: Pagination | undefined;
+}
+interface NonCollectible {
+  data: ResourceData;
+}
+interface Collectible {
+  data: ResourceData[];
+  cursor?: Cursor | undefined;
+  pagination?: Pagination | undefined;
+}
+interface ResponseData<R extends ResourceData = any> extends Resource$1 {
+  data: R;
+  meta?: MetaData | undefined;
+}
+type PaginatedMetaData<R extends Collectible = Collectible> = MetaData & Omit<R, 'data'>;
+interface ResponseDataCollection<R extends Collectible | undefined = undefined> extends ResourceData {
+  data: R extends Collectible ? R['data'] : R;
+  meta?: R extends Collectible ? PaginatedMetaData<R> | undefined : undefined;
+}
+/**
+ * @description A type that represents the body of a response for a collection of resources.
+ * It can be either an array of ResourceData objects or a Collectible object, which contains an
+ * array of ResourceData objects. The type also includes the meta property, which is optional
+ * and can contain any additional metadata related to the response.
+ * @example
+ * const collectionResponse: CollectionBody = {
+ *   data: [
+ *     { id: 1, name: 'Resource 1' },
+ *     { id: 2, name: 'Resource 2' }
+ *   ],
+ *   meta: {
+ *     pagination: {
+ *       currentPage: 1,
+ *       total: 2
+ *     }
+ *   }
+ * };
+ */
+type CollectionBody<R extends ResourceData[] | Collectible = ResourceData[]> = ResponseDataCollection<R extends Collectible ? R : {
+  data: R;
+}>;
+/**
+ * @description A type that represents the body of a response for a single resource.
+ * It can be either a ResourceData object or a NonCollectible object, which contains a
+ * ResourceData object. The type also includes the meta property, which is optional and can
+ * contain any additional metadata related to the response.
+ * @example
+ * const resourceResponse: ResourceBody = {
+ *   data: {
+ *     id: 1,
+ *     name: 'Resource Name',
+ *     description: 'Resource Description'
+ *   },
+ *   meta: {
+ *     timestamp: '2024-06-01T12:00:00Z'
+ *   }
+ * };
+ */
+type ResourceBody<R extends ResourceData | NonCollectible = ResourceData> = ResponseData<R extends NonCollectible ? R : {
+  data: R;
+}>;
+/**
+ * @description A type that represents the pagination information for a collection of resources. It includes properties such as currentPage, from, to, perPage, total, firstPage, lastPage, prevPage, and nextPage. All properties are optional and can be undefined if not applicable.
+ * @example
+ * const paginationInfo: Pagination = {
+ *   currentPage: 1,
+ *   from: 1,
+ *   to: 10,
+ *   perPage: 10,
+ *   total: 100,
+ *   firstPage: 1,
+ *   lastPage: 10,
+ *   prevPage: null,
+ *   nextPage: 2
+ * };
+ */
+interface Pagination {
+  currentPage?: number | undefined;
+  from?: number | undefined;
+  to?: number | undefined;
+  perPage?: number | undefined;
+  total?: number | undefined;
+  firstPage?: number | undefined;
+  lastPage?: number | undefined;
+  prevPage?: number | undefined;
+  nextPage?: number | undefined;
+}
+/**
+ * @description A type that represents the cursor information for pagination. It includes properties such as before and after, which are optional and can be undefined if not applicable. The before property represents the cursor for the previous page, while the after property represents the cursor for the next page.
+ * @example
+ * const cursorInfo: Cursor = {
+ *   previous: 'cursor-for-previous-page',
+ *   next: 'cursor-for-next-page'
+ * };
+ */
+interface Cursor {
+  previous?: string | undefined;
+  next?: string | undefined;
+}
+//#endregion
+//#region src/ServerResponse.d.ts
+declare class ServerResponse<R extends NonCollectible | Collectible | ResourceData[] | ResourceData = ResourceData> {
+  #private;
+  private response;
+  private body;
+  private _status;
+  headers: Record<string, string>;
+  constructor(response: H3Event['res'], body: R);
+  constructor(response: Response, body: R);
+  /**
+   * Set the HTTP status code for the response
+   *
+   * @param status
+   * @returns The current ServerResponse instance
+   */
+  setStatusCode(status: number): this;
+  /**
+   * Get the current HTTP status code for the response
+   *
+   * @returns
+   */
+  status(): number;
+  /**
+   * Get the current HTTP status text for the response
+   *
+   * @returns
+   */
+  statusText(): string | undefined;
+  /**
+   * Set a cookie in the response header
+   *
+   * @param name The name of the cookie
+   * @param value The value of the cookie
+   * @param options Optional cookie attributes (e.g., path, domain, maxAge)
+   * @returns The current ServerResponse instance
+   */
+  setCookie(name: string, value: string, options?: Record<string, any>): this;
+  /**
+   * Convert the resource to a JSON response body
+   *
+   * @param headers Optional headers to add to the response
+   * @returns The current ServerResponse instance
+   */
+  setHeaders(headers: Record<string, string>): this;
+  /**
+   * Add a single header to the response
+   *
+   * @param key The name of the header
+   * @param value The value of the header
+   * @returns The current ServerResponse instance
+   */
+  header(key: string, value: string): this;
+  /**
+   * 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
+   * @returns A promise that resolves to the result of the onfulfilled or onrejected callback
+   */
+  then<TResult1 = R, TResult2 = never>(onfulfilled?: ((value: R) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+  /**
+   * Promise-like catch method to handle rejected state of the promise
+   *
+   * @param onrejected
+   * @returns
+   */
+  catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<R | TResult>;
+  /**
+   * Promise-like finally method to handle cleanup after promise is settled
+   *
+   * @param onfinally
+   * @returns
+   */
+  finally(onfinally?: (() => void) | null): Promise<void>;
+}
+//#endregion
+//#region src/ResourceCollection.d.ts
+/**
+ * ResourceCollection class to handle API resource transformation and response building for collections
+ */
+declare class ResourceCollection<R extends ResourceData[] | Collectible = ResourceData[], T extends ResourceData = any> {
+  private res?;
+  [key: string]: any;
+  body: CollectionBody<R>;
+  resource: R;
+  collects?: typeof Resource<T>;
+  private called;
+  constructor(rsc: R);
+  constructor(rsc: R, res: Response);
+  /**
+   * Get the original resource data
+   */
+  data(): (R extends Collectible ? R["data"][number] : R extends ResourceData[] ? R[number] : never)[];
+  /**
+   * Convert resource to JSON response format
+   *
+   * @returns
+   */
+  json(): this;
+  /**
+   * Flatten resource to return original data
+   *
+   * @returns
+   */
+  toArray(): (R extends Collectible ? R['data'][number] : R extends ResourceData[] ? R[number] : never)[];
+  /**
+   * Add additional properties to the response body
+   *
+   * @param extra  Additional properties to merge into the response body
+   * @returns
+   */
+  additional<X extends Record<string, any>>(extra: X): this;
+  response(): ServerResponse<CollectionBody<R>>;
+  response(res: H3Event['res']): ServerResponse<CollectionBody<R>>;
+  setCollects(collects: typeof Resource<T>): this;
+  /**
+   * 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
+   * @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>;
+  /**
+   * Promise-like catch method to handle rejected state of the promise
+   *
+   * @param onrejected
+   * @returns
+   */
+  catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<CollectionBody<R> | TResult>;
+  /**
+   * Promise-like finally method to handle cleanup after promise is settled
+   *
+   * @param onfinally
+   * @returns
+   */
+  finally(onfinally?: (() => void) | null): Promise<void>;
+}
+//#endregion
+//#region src/Resource.d.ts
+/**
+ * Resource class to handle API resource transformation and response building
+ */
+declare class Resource<R extends ResourceData | NonCollectible = ResourceData> {
+  private res?;
+  [key: string]: any;
+  body: ResourceBody<R>;
+  resource: R;
+  private called;
+  constructor(rsc: R, res?: Response | undefined);
+  /**
+   * Create a ResourceCollection from an array of resource data or a Collectible instance
+   *
+   * @param data
+   * @returns
+   */
+  static collection<C extends ResourceData[] | Collectible = ResourceData[], T extends ResourceData = any>(data: C): ResourceCollection<C, T>;
+  /**
+   * Get the original resource data
+   */
+  data(): R extends NonCollectible ? R["data"] : R;
+  /**
+   * Convert resource to JSON response format
+   *
+   * @returns
+   */
+  json(): this;
+  /**
+   * Flatten resource to array format (for collections) or return original data for single resources
+   *
+   * @returns
+   */
+  toArray(): R extends NonCollectible ? R['data'] : R;
+  /**
+   * Add additional properties to the response body
+   *
+   * @param extra  Additional properties to merge into the response body
+   * @returns
+   */
+  additional<X extends Record<string, any>>(extra: X): this;
+  response(): ServerResponse<ResourceBody<R>>;
+  response(res: H3Event['res']): ServerResponse<ResourceBody<R>>;
+  /**
+   * 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
+   * @returns A promise that resolves to the result of the onfulfilled or onrejected callback
+   */
+  then<TResult1 = ResourceBody<R>, TResult2 = never>(onfulfilled?: ((value: ResourceBody<R>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+  /**
+   * Promise-like catch method to handle rejected state of the promise
+   *
+   * @param onrejected
+   * @returns
+   */
+  catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<ResourceBody<R> | TResult>;
+  /**
+   * Promise-like finally method to handle cleanup after promise is settled
+   *
+   * @param onfinally
+   * @returns
+   */
+  finally(onfinally?: (() => void) | null): Promise<void>;
+}
+//#endregion
+export { ApiResource, Resource };