From 28d2a5347a6b9e6d3335c4b39c1f076f2bc05b97 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 3 Jun 2024 11:18:02 +0300 Subject: [PATCH] chore(types, utils): added TSDocs for file provider module (#7553) * chore(types, utils): added TSDocs for file provider module * fix import --- packages/core/types/src/file/provider.ts | 9 +- .../utils/src/file/abstract-file-provider.ts | 115 ++++++++++++++++++ .../constants/merger-custom-options/file.ts | 1 + 3 files changed, 117 insertions(+), 8 deletions(-) diff --git a/packages/core/types/src/file/provider.ts b/packages/core/types/src/file/provider.ts index 9a31bef00f..d7c6a6b140 100644 --- a/packages/core/types/src/file/provider.ts +++ b/packages/core/types/src/file/provider.ts @@ -9,8 +9,7 @@ export type ProviderFileResultDTO = { */ url: string /** - * The file's key. This key is used in other operations, - * such as deleting a file. + * The file's key. */ key: string } @@ -68,12 +67,6 @@ export type ProviderUploadFileDTO = { content: string } -/** - * ## Overview - * - * File provider interface for the file module. - * - */ export interface IFileProvider { /** * This method is used to upload a file diff --git a/packages/core/utils/src/file/abstract-file-provider.ts b/packages/core/utils/src/file/abstract-file-provider.ts index 2aa27440c3..1b662faaa0 100644 --- a/packages/core/utils/src/file/abstract-file-provider.ts +++ b/packages/core/utils/src/file/abstract-file-provider.ts @@ -1,21 +1,136 @@ import { FileTypes, IFileProvider } from "@medusajs/types" +/** + * ### constructor + * + * The constructor allows you to access resources from the module's container using the first parameter, + * and the module's options using the second parameter. + * + * If you're creating a client or establishing a connection with a third-party service, do it in the constructor. + * + * #### Example + * + * ```ts + * import { Logger } from "@medusajs/types" + * import { AbstractFileProviderService } from "@medusajs/utils" + * + * type InjectedDependencies = { + * logger: Logger + * } + * + * type Options = { + * apiKey: string + * } + * + * class MyFileProviderService extends AbstractFileProviderService { + * protected logger_: Logger + * protected options_: Options + * // assuming you're initializing a client + * protected client + * + * constructor ( + * { logger }: InjectedDependencies, + * options: Options + * ) { + * super() + * + * this.logger_ = logger + * this.options_ = options + * + * // assuming you're initializing a client + * this.client = new Client(options) + * } + * } + * + * export default MyFileProviderService + * ``` + */ export class AbstractFileProviderService implements IFileProvider { + /** + * @ignore + */ static identifier: string + /** + * @ignore + */ getIdentifier() { return (this.constructor as any).identifier } + /** + * This method uploads a file using your provider's custom logic. + * + * @param {FileTypes.ProviderUploadFileDTO} file - The file to upload + * @returns {Promise} The uploaded file's details. + * + * @example + * class MyFileProviderService extends AbstractFileProviderService { + * // ... + * async upload( + * file: ProviderUploadFileDTO + * ): Promise { + * // TODO upload file to third-party provider + * // or using custom logic + * + * return { + * url: "some-url.com", + * key: "file-name" + * } + * } + * } + */ async upload( file: FileTypes.ProviderUploadFileDTO ): Promise { throw Error("upload must be overridden by the child class") } + + /** + * This method deletes the file from storage. + * + * @param {FileTypes.ProviderDeleteFileDTO} file - The details of the file to delete. + * @returns {Promise} Resolves when the file is deleted. + * + * @example + * class MyFileProviderService extends AbstractFileProviderService { + * // ... + * async delete(file: ProviderDeleteFileDTO): Promise { + * // TODO logic to remove the file from storage + * // Use the `file.fileKey` to delete the file + * // for example: + * this.client.delete(file.fileKey) + * } + * } + */ async delete(file: FileTypes.ProviderDeleteFileDTO): Promise { throw Error("delete must be overridden by the child class") } + /** + * This method is used to retrieve a download URL of the file. For some providers, + * such as S3, a presigned URL indicates a temporary URL to get access to a file. + * + * If your provider doesn’t perform or offer a similar functionality, you can + * return the URL to download the file. + * + * @param {FileTypes.ProviderGetFileDTO} fileData - The details of the file to get its + * presigned URL. + * @returns {Promise} The file's presigned URL. + * + * @example + * class MyFileProviderService extends AbstractFileProviderService { + * // ... + * async getPresignedDownloadUrl( + * fileData: ProviderGetFileDTO + * ): Promise { + * // TODO logic to get the presigned URL + * // Use the `file.fileKey` to delete the file + * // for example: + * return this.client.getPresignedUrl(fileData.fileKey) + * } + * } + */ async getPresignedDownloadUrl( fileData: FileTypes.ProviderGetFileDTO ): Promise { diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts index 6706f0abc0..e871238d8d 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts @@ -4,6 +4,7 @@ const fileOptions: FormattingOptionsType = { "^file/.*AbstractFileProviderService": { reflectionGroups: { Properties: false, + Constructors: false, }, reflectionDescription: `In this document, you’ll learn how to create a file provider module and the methods you must implement in its main service.`, frontmatterData: {