or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

amount-utilities.mdcontainer-di.mddata-utilities.mderror-handling.mdindex.mdserver-utilities.mdutility-functions.md
tile.json

tessl/npm-medusa-core-utils

Core utilities for Medusa e-commerce platform including error handling, DI container, amount calculations, and configuration parsing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/medusa-core-utils@1.2.x

To install, run

npx @tessl/cli install tessl/npm-medusa-core-utils@1.2.0

index.mddocs/

Medusa Core Utils

Medusa Core Utils provides essential utilities for the Medusa e-commerce platform. It includes standardized error handling, dependency injection container functionality, amount computation utilities for financial calculations, country code and currency handling, configuration file parsing, graceful server shutdown mechanisms, CORS origin parsing, and various data transformation utilities.

Package Information

  • Package Name: medusa-core-utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install medusa-core-utils

Core Imports

import { 
  MedusaError, 
  createMedusaContainer, 
  computerizeAmount,
  humanizeAmount,
  countries,
  isoCountryLookup,
  getConfigFile,
  GracefulShutdownServer,
  buildRegexpIfValid,
  isDefined,
  parseCorsOrigins,
  transformIdableFields,
  zeroDecimalCurrencies,
  getMedusaVersion,
  indexTypes,
  createRequireFromPath
} from "medusa-core-utils";

For CommonJS:

const { 
  MedusaError, 
  createMedusaContainer, 
  computerizeAmount,
  humanizeAmount,
  countries,
  isoCountryLookup,
  getConfigFile,
  GracefulShutdownServer,
  buildRegexpIfValid,
  isDefined,
  parseCorsOrigins,
  transformIdableFields,
  zeroDecimalCurrencies,
  getMedusaVersion,
  indexTypes,
  createRequireFromPath
} = require("medusa-core-utils");

Basic Usage

import { 
  MedusaError, 
  createMedusaContainer, 
  computerizeAmount, 
  humanizeAmount,
  countries,
  isoCountryLookup
} from "medusa-core-utils";

// Error handling
throw new MedusaError(
  MedusaError.Types.INVALID_DATA, 
  "Invalid user input", 
  MedusaError.Codes.INSUFFICIENT_INVENTORY
);

// Dependency injection
const container = createMedusaContainer();
container.register("userService", asClass(UserService));

// Amount calculations
const dbAmount = computerizeAmount(19.99, "usd"); // 1999 (cents)
const displayAmount = humanizeAmount(1999, "usd"); // 19.99

// Country lookup
const countryCode = isoCountryLookup("United States"); // "US"

Architecture

Medusa Core Utils is organized around several key functional areas:

  • Error Management: Standardized error classes and types for consistent error handling across Medusa services
  • Dependency Injection: Enhanced Awilix container with additional registration patterns for service management
  • Financial Utilities: Currency-aware amount conversion between display and storage formats
  • Internationalization: Complete country code lookup and validation utilities
  • Configuration Management: Dynamic configuration file loading with error handling
  • Server Lifecycle: Graceful shutdown patterns for HTTP servers
  • Data Processing: Utilities for data transformation, validation, and parsing

Capabilities

Error Handling

Standardized error handling with predefined error types and codes for consistent error management across Medusa applications.

class MedusaError extends Error {
  constructor(type: string, message: string, code?: string, ...params: any);
  public type: string;
  public message: string;
  public code?: string;
  public date: Date;
  
  public static Types: {
    DB_ERROR: "database_error";
    DUPLICATE_ERROR: "duplicate_error";
    INVALID_ARGUMENT: "invalid_argument";
    INVALID_DATA: "invalid_data";
    UNAUTHORIZED: "unauthorized";
    NOT_FOUND: "not_found";
    NOT_ALLOWED: "not_allowed";
    UNEXPECTED_STATE: "unexpected_state";
    CONFLICT: "conflict";
    PAYMENT_AUTHORIZATION_ERROR: "payment_authorization_error";
  };
  
  public static Codes: {
    INSUFFICIENT_INVENTORY: "insufficient_inventory";
    CART_INCOMPATIBLE_STATE: "cart_incompatible_state";
  };
}

Error Handling

Container & Dependency Injection

Enhanced Awilix dependency injection container with additional registration patterns optimized for Medusa's service architecture.

type MedusaContainer = AwilixContainer & {
  registerAdd: <T>(name: string, registration: T) => MedusaContainer;
  createScope: () => MedusaContainer;
};

function createMedusaContainer(...args): MedusaContainer;

Container & Dependency Injection

Amount Utilities

Currency-aware financial calculation utilities for converting between display and database storage formats, with support for zero-decimal currencies.

function computerizeAmount(amount: number, currency: string): number;
function humanizeAmount(amount: number, currency: string): number;
const zeroDecimalCurrencies: string[];

Amount Utilities

Data Utilities

Comprehensive data processing utilities including country code lookup, CORS origin parsing, field transformations, and validation functions.

type Country = {
  alpha2: string;
  name: string;
  alpha3: string;
  numeric: string;
};

const countries: Country[];
function isoCountryLookup(country: string): string;
function parseCorsOrigins(str: string): (string | RegExp)[];
function transformIdableFields<T, TFields, TOutput>(
  obj: T, 
  fields: TFields
): TOutput;
function isDefined<T>(val: T): val is T extends undefined ? never : T;

Data Utilities

Server Utilities

Server lifecycle management including graceful shutdown patterns, configuration file loading, and version detection utilities.

abstract class GracefulShutdownServer {
  public isShuttingDown: boolean;
  public abstract shutdown(timeout?: number): Promise<void>;
  public static create<T extends Server>(
    originalServer: T,
    waitingResponseTime?: number
  ): T & GracefulShutdownServer;
}

function getConfigFile<TConfig = unknown>(
  rootDir: string,
  configName: string
): { configModule: TConfig; configFilePath: string; error?: any };

function getMedusaVersion(): string;

Server Utilities

Utility Functions

General-purpose utility functions for regular expression validation, require path creation, and type indexing.

function buildRegexpIfValid(str: string): RegExp | undefined;
function createRequireFromPath(filename: string): NodeRequire;
const indexTypes: {
  products: "products";
};

Utility Functions