IFileService

Overview

A file service class is defined in a TypeScript or JavaScript file that’s created in the src/services directory. The class must extend the AbstractFileService class imported from the @medusajs/medusa package.

Based on services’ naming conventions, the file’s name should be the slug version of the file service’s name without service, and the class’s name should be the pascal case of the file service’s name following by Service.

For example, create the file src/services/local-file.ts with the following content:

src/services/local-file.ts

import { AbstractFileService } from "@medusajs/medusa"
import {
  DeleteFileType,
  FileServiceGetUploadStreamResult,
  FileServiceUploadResult,
  GetUploadedFileType,
  UploadStreamDescriptorType,
} from "@medusajs/types"

class LocalFileService extends AbstractFileService {
  async upload(
    fileData: Express.Multer.File
  ): Promise<FileServiceUploadResult> {
    throw new Error("Method not implemented.")
  }
  async uploadProtected(
    fileData: Express.Multer.File
  ): Promise<FileServiceUploadResult> {
    throw new Error("Method not implemented.")
  }
  async delete(fileData: DeleteFileType): Promise<void> {
    throw new Error("Method not implemented.")
  }
  async getUploadStreamDescriptor(
    fileData: UploadStreamDescriptorType
  ): Promise<FileServiceGetUploadStreamResult> {
    throw new Error("Method not implemented.")
  }
  async getDownloadStream(
    fileData: GetUploadedFileType
  ): Promise<NodeJS.ReadableStream> {
    throw new Error("Method not implemented.")
  }
  async getPresignedDownloadUrl(
    fileData: GetUploadedFileType
  ): Promise<string> {
    throw new Error("Method not implemented.")
  }
}

export default LocalFileService

Multer Typing

The examples implement a file service supporting local uploads.

If you’re using TypeScript and you're following along with the implementation, you should install the Multer types package in the root of your Medusa backend to resolve errors within your file service types:

• npm
• Yarn
• pnpm

npm install @types/multer

yarn add @types/multer

pnpm add @types/multer

---

Properties

manager_EntityManagerRequired

transactionManager_undefined | EntityManagerRequired

__container__anyRequired

__configModule__Record<string, unknown>

__moduleDeclaration__Record<string, unknown>

---

Accessors

activeManager_

Returns

EntityManagerEntityManagerRequired

---

Methods

upload

This method is used to upload a file to the Medusa backend.

Example

class LocalFileService extends AbstractFileService {
  // ...
  async upload(
    fileData: Express.Multer.File
  ): Promise<FileServiceUploadResult> {
    const filePath =
      `${this.publicPath}/${fileData.originalname}`
    fs.copyFileSync(fileData.path, filePath)
    return {
      url: `${this.serverUrl}/${filePath}`,
      key: filePath,
    }
  }
  // ...
}

Tip

This example does not account for duplicate names to maintain simplicity in this guide. So, an uploaded file can replace another existing file that has the same name.

Parameters

fileFileRequired

A multer file object. The file is uploaded to a temporary directory by default. Among the file’s details, you can access the file’s path in the path property of the file object.

Returns

PromisePromise<FileServiceUploadResult>Required

The details of the upload's result.

uploadProtected

This method is used to upload a file to the Medusa backend, but to a protected storage. Typically, this would be used to store files that shouldn’t be accessible by using the file’s URL or should only be accessible by authenticated users. For example, exported or imported CSV files.

Example

class LocalFileService extends AbstractFileService {
  // ...
  async uploadProtected(
    fileData: Express.Multer.File
  ): Promise<FileServiceUploadResult> {
    const filePath =
      `${this.protectedPath}/${fileData.originalname}`
    fs.copyFileSync(fileData.path, filePath)
    return {
      url: `${this.serverUrl}/${filePath}`,
      key: filePath
    }
  }
  // ...
}

Tip

This example does not account for duplicate names to maintain simplicity in this guide. So, an uploaded file can replace another existing file that has the same name.

Parameters

fileFileRequired

A multer file object. The file is uploaded to a temporary directory by default. Among the file’s details, you can access the file’s path in the path property of the file object.

Returns

PromisePromise<FileServiceUploadResult>Required

The details of the upload's result.

delete

This method is used to delete a file from storage.

Example

class LocalFileService extends AbstractFileService {

  async delete(
    fileData: DeleteFileType
  ): Promise<void> {
    fs.rmSync(fileData.fileKey)
  }

  // ...
}

Parameters

fileDataDeleteFileTypeRequired

The details of the file to remove.

Returns

PromisePromise<void>Required

Resolves when the file is deleted successfully.

getUploadStreamDescriptor

This method is used to retrieve a write stream to be used to upload a file.

Example

// ...
import { Stream } from "stream"

class LocalFileService extends AbstractFileService {
  // ...
  async getUploadStreamDescriptor({
      name,
      ext,
      isPrivate = true,
    }: UploadStreamDescriptorType
  ): Promise<FileServiceGetUploadStreamResult> {
    const filePath = `${isPrivate ?
      this.publicPath : this.protectedPath
    }/${name}.${ext}`

    const pass = new Stream.PassThrough()
    const writeStream = fs.createWriteStream(filePath)

    pass.pipe(writeStream)

    return {
      writeStream: pass,
      promise: Promise.resolve(),
      url: `${this.serverUrl}/${filePath}`,
      fileKey: filePath,
    }
  }
  // ...
}

Parameters

fileDataUploadStreamDescriptorTypeRequired

The details of the file being uploaded.

Returns

PromisePromise<FileServiceGetUploadStreamResult>Required

The result of the file-stream upload.

getDownloadStream

This method is used to retrieve a read stream for a file, which can then be used to download the file.

Example

class LocalFileService extends AbstractFileService {

  async getDownloadStream({
      fileKey,
      isPrivate = true,
    }: GetUploadedFileType
  ): Promise<NodeJS.ReadableStream> {
    const filePath = `${isPrivate ?
      this.publicPath : this.protectedPath
    }/${fileKey}`
    const readStream = fs.createReadStream(filePath)

    return readStream
  }

  // ...
}

Parameters

fileDataGetUploadedFileTypeRequired

The details of the file.

Returns

PromisePromise<ReadableStream>Required

The read stream to read and download the file.

getPresignedDownloadUrl

This method is used to retrieve a download URL of the file. For some file services, such as S3, a presigned URL indicates a temporary URL to get access to a file.

If your file service doesn’t perform or offer a similar functionality, you can just return the URL to download the file.

Example

class LocalFileService extends AbstractFileService {

  async getPresignedDownloadUrl({
      fileKey,
      isPrivate = true,
    }: GetUploadedFileType
  ): Promise<string> {
    // Local upload doesn't provide
    // support for presigned URLs,
    // so just return the file's URL.

    const filePath = `${isPrivate ?
      this.publicPath : this.protectedPath
    }/${fileKey}`
    return `${this.serverUrl}/${filePath}`
  }

  // ...
}

Parameters

fileDataGetUploadedFileTypeRequired

The details of the file.

Returns

PromisePromise<string>Required

The presigned URL to download the file

withTransaction

Parameters

transactionManagerEntityManager

Returns

thisthisRequired

shouldRetryTransaction_

Parameters

errRecord<string, unknown> | objectRequired

Returns

booleanbooleanRequired

atomicPhase_

Wraps some work within a transactional block. If the service already has a transaction manager attached this will be reused, otherwise a new transaction manager is created.

Type Parameters

TResultobjectRequired

TErrorobjectRequired

Parameters

work(transactionManager: EntityManager) => Promise<TResult>Required

the transactional work to be done

isolationOrErrorHandlerIsolationLevel | (error: TError) => Promise<void | TResult>

the isolation level to be used for the work.

maybeErrorHandlerOrDontFail(error: TError) => Promise<void | TResult>

Potential error handler

Returns

PromisePromise<TResult>Required

the result of the transactional work