0
# Medusa Core Utils
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: medusa-core-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install medusa-core-utils`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  MedusaError, 
16
  createMedusaContainer, 
17
  computerizeAmount,
18
  humanizeAmount,
19
  countries,
20
  isoCountryLookup,
21
  getConfigFile,
22
  GracefulShutdownServer,
23
  buildRegexpIfValid,
24
  isDefined,
25
  parseCorsOrigins,
26
  transformIdableFields,
27
  zeroDecimalCurrencies,
28
  getMedusaVersion,
29
  indexTypes,
30
  createRequireFromPath
31
} from "medusa-core-utils";
32
```
33

34
For CommonJS:
35

36
```javascript
37
const { 
38
  MedusaError, 
39
  createMedusaContainer, 
40
  computerizeAmount,
41
  humanizeAmount,
42
  countries,
43
  isoCountryLookup,
44
  getConfigFile,
45
  GracefulShutdownServer,
46
  buildRegexpIfValid,
47
  isDefined,
48
  parseCorsOrigins,
49
  transformIdableFields,
50
  zeroDecimalCurrencies,
51
  getMedusaVersion,
52
  indexTypes,
53
  createRequireFromPath
54
} = require("medusa-core-utils");
55
```
56

57
## Basic Usage
58

59
```typescript
60
import { 
61
  MedusaError, 
62
  createMedusaContainer, 
63
  computerizeAmount, 
64
  humanizeAmount,
65
  countries,
66
  isoCountryLookup
67
} from "medusa-core-utils";
68

69
// Error handling
70
throw new MedusaError(
71
  MedusaError.Types.INVALID_DATA, 
72
  "Invalid user input", 
73
  MedusaError.Codes.INSUFFICIENT_INVENTORY
74
);
75

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

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

84
// Country lookup
85
const countryCode = isoCountryLookup("United States"); // "US"
86
```
87

88
## Architecture
89

90
Medusa Core Utils is organized around several key functional areas:
91

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

100
## Capabilities
101

102
### Error Handling
103

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

106
```typescript { .api }
107
class MedusaError extends Error {
108
  constructor(type: string, message: string, code?: string, ...params: any);
109
  public type: string;
110
  public message: string;
111
  public code?: string;
112
  public date: Date;
113
  
114
  public static Types: {
115
    DB_ERROR: "database_error";
116
    DUPLICATE_ERROR: "duplicate_error";
117
    INVALID_ARGUMENT: "invalid_argument";
118
    INVALID_DATA: "invalid_data";
119
    UNAUTHORIZED: "unauthorized";
120
    NOT_FOUND: "not_found";
121
    NOT_ALLOWED: "not_allowed";
122
    UNEXPECTED_STATE: "unexpected_state";
123
    CONFLICT: "conflict";
124
    PAYMENT_AUTHORIZATION_ERROR: "payment_authorization_error";
125
  };
126
  
127
  public static Codes: {
128
    INSUFFICIENT_INVENTORY: "insufficient_inventory";
129
    CART_INCOMPATIBLE_STATE: "cart_incompatible_state";
130
  };
131
}
132
```
133

134
[Error Handling](./error-handling.md)
135

136
### Container & Dependency Injection
137

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

140
```typescript { .api }
141
type MedusaContainer = AwilixContainer & {
142
  registerAdd: <T>(name: string, registration: T) => MedusaContainer;
143
  createScope: () => MedusaContainer;
144
};
145

146
function createMedusaContainer(...args): MedusaContainer;
147
```
148

149
[Container & Dependency Injection](./container-di.md)
150

151
### Amount Utilities
152

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

155
```typescript { .api }
156
function computerizeAmount(amount: number, currency: string): number;
157
function humanizeAmount(amount: number, currency: string): number;
158
const zeroDecimalCurrencies: string[];
159
```
160

161
[Amount Utilities](./amount-utilities.md)
162

163
### Data Utilities
164

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

167
```typescript { .api }
168
type Country = {
169
  alpha2: string;
170
  name: string;
171
  alpha3: string;
172
  numeric: string;
173
};
174

175
const countries: Country[];
176
function isoCountryLookup(country: string): string;
177
function parseCorsOrigins(str: string): (string | RegExp)[];
178
function transformIdableFields<T, TFields, TOutput>(
179
  obj: T, 
180
  fields: TFields
181
): TOutput;
182
function isDefined<T>(val: T): val is T extends undefined ? never : T;
183
```
184

185
[Data Utilities](./data-utilities.md)
186

187
### Server Utilities
188

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

191
```typescript { .api }
192
abstract class GracefulShutdownServer {
193
  public isShuttingDown: boolean;
194
  public abstract shutdown(timeout?: number): Promise<void>;
195
  public static create<T extends Server>(
196
    originalServer: T,
197
    waitingResponseTime?: number
198
  ): T & GracefulShutdownServer;
199
}
200

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

206
function getMedusaVersion(): string;
207
```
208

209
[Server Utilities](./server-utilities.md)
210

211
### Utility Functions
212

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

215
```typescript { .api }
216
function buildRegexpIfValid(str: string): RegExp | undefined;
217
function createRequireFromPath(filename: string): NodeRequire;
218
const indexTypes: {
219
  products: "products";
220
};
221
```
222

223
[Utility Functions](./utility-functions.md)