0
# PNPM Catalogs Config
1

2
@pnpm/catalogs.config provides utilities for normalizing catalog configurations from pnpm workspace manifests. It processes pnpm-workspace.yaml contents and creates unified catalog configuration objects by combining implicit default catalogs with named catalogs, with validation to prevent duplicate default catalog definitions.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/catalogs.config
7
- **Package Type**: npm (internal pnpm monorepo package)
8
- **Language**: TypeScript
9
- **Installation**: Part of pnpm monorepo - not independently installable
10

11
## Core Imports
12

13
```typescript
14
import { getCatalogsFromWorkspaceManifest, checkDefaultCatalogIsDefinedOnce } from "@pnpm/catalogs.config";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { getCatalogsFromWorkspaceManifest, checkDefaultCatalogIsDefinedOnce } = require("@pnpm/catalogs.config");
21
```
22

23
## Dependencies
24

25
This package depends on:
26
- `@pnpm/error` - Error handling utilities
27
- `@pnpm/catalogs.types` - Type definitions for catalog structures  
28
- `@pnpm/workspace.read-manifest` - Workspace manifest type definitions
29

30
## Basic Usage
31

32
```typescript
33
import { getCatalogsFromWorkspaceManifest, checkDefaultCatalogIsDefinedOnce } from "@pnpm/catalogs.config";
34

35
// Process a workspace manifest with implicit default catalog
36
const result1 = getCatalogsFromWorkspaceManifest({
37
  catalog: {
38
    lodash: '^4.17.21',
39
    react: '^18.0.0'
40
  },
41
  catalogs: {
42
    testing: {
43
      jest: '^29.0.0',
44
      '@testing-library/react': '^13.0.0'
45
    }
46
  }
47
});
48
// Result: {
49
//   default: { lodash: '^4.17.21', react: '^18.0.0' },
50
//   testing: { jest: '^29.0.0', '@testing-library/react': '^13.0.0' }
51
// }
52

53
// Process a workspace manifest with explicit default catalog
54
const result2 = getCatalogsFromWorkspaceManifest({
55
  catalogs: {
56
    default: {
57
      lodash: '^4.17.21',
58
      react: '^18.0.0'  
59
    },
60
    testing: {
61
      jest: '^29.0.0'
62
    }
63
  }
64
});
65
// Result: {
66
//   default: { lodash: '^4.17.21', react: '^18.0.0' },
67
//   testing: { jest: '^29.0.0' }
68
// }
69

70
// Handle missing workspace manifest
71
const result3 = getCatalogsFromWorkspaceManifest(undefined);
72
// Result: {}
73

74
// Validate catalog configuration before processing
75
const manifest = {
76
  catalog: { foo: '^1.0.0' },
77
  catalogs: { testing: { bar: '^2.0.0' } }
78
};
79

80
try {
81
  checkDefaultCatalogIsDefinedOnce(manifest);
82
  // No error - validation passed
83
} catch (error) {
84
  // Handle validation error
85
}
86
```
87

88
## Capabilities
89

90
### Catalog Configuration Normalization
91

92
Normalizes catalog configurations from pnpm workspace manifests into a unified structure.
93

94
```typescript { .api }
95
/**
96
 * Creates a normalized catalogs configuration from pnpm workspace manifest contents.
97
 * Combines implicit default catalogs (defined via 'catalog' field) with named catalogs
98
 * (defined via 'catalogs' field). Returns empty object for null/undefined manifests.
99
 * 
100
 * @param workspaceManifest - Workspace manifest object or undefined
101
 * @returns Normalized catalogs configuration
102
 * @throws PnpmError with code 'INVALID_CATALOGS_CONFIGURATION' if default catalog defined multiple times
103
 */
104
function getCatalogsFromWorkspaceManifest(
105
  workspaceManifest: Pick<WorkspaceManifest, 'catalog' | 'catalogs'> | undefined
106
): Catalogs;
107
```
108

109
### Catalog Validation
110

111
Validates that the default catalog is not defined in multiple locations within a workspace manifest.
112

113
```typescript { .api }
114
/**
115
 * Validates that the default catalog is defined only once in a workspace manifest.
116
 * Throws an error if both 'catalog' and 'catalogs.default' fields are present.
117
 * 
118
 * @param manifest - Workspace manifest object with catalog definitions
119
 * @throws PnpmError with code 'INVALID_CATALOGS_CONFIGURATION' if default catalog defined multiple times
120
 */
121
function checkDefaultCatalogIsDefinedOnce(
122
  manifest: Pick<WorkspaceManifest, 'catalog' | 'catalogs'>
123
): void;
124
```
125

126

127
## Types
128

129
```typescript { .api }
130
/**
131
 * Normalized catalogs configuration structure
132
 */
133
interface Catalogs {
134
  /** The default catalog - can be defined via 'catalog' field or 'catalogs.default' */
135
  readonly default?: Catalog;
136
  /** Named catalogs mapped by catalog name */
137
  readonly [catalogName: string]: Catalog | undefined;
138
}
139

140
/**
141
 * Individual catalog containing dependency name to version mappings
142
 */
143
interface Catalog {
144
  readonly [dependencyName: string]: string | undefined;
145
}
146

147
/**
148
 * Structure of pnpm-workspace.yaml file (partial)
149
 */
150
interface WorkspaceManifest {
151
  /** Implicit default catalog definition */
152
  catalog?: WorkspaceCatalog;
153
  /** Named catalogs including optional explicit default */
154
  catalogs?: WorkspaceNamedCatalogs;
155
  /** Other fields... */
156
}
157

158
/**
159
 * Workspace catalog with dependency mappings
160
 */
161
interface WorkspaceCatalog {
162
  readonly [dependencyName: string]: string;
163
}
164

165
/**
166
 * Named catalogs dictionary
167
 */
168
interface WorkspaceNamedCatalogs {
169
  readonly [catalogName: string]: WorkspaceCatalog;
170
}
171

172
/**
173
 * PNPM error class imported from @pnpm/error package
174
 */
175
type PnpmError = Error & {
176
  readonly code: string;
177
};
178
```
179

180
## Error Handling
181

182
The package throws `PnpmError` exceptions for validation failures:
183

184
### INVALID_CATALOGS_CONFIGURATION
185

186
Thrown when the default catalog is defined in both `catalog` and `catalogs.default` fields.
187

188
```typescript
189
// This will throw an error
190
getCatalogsFromWorkspaceManifest({
191
  catalog: { lodash: '^4.17.21' },  // implicit default
192
  catalogs: {
193
    default: { react: '^18.0.0' }   // explicit default - conflict!
194
  }
195
});
196
// Throws: PnpmError with message "The 'default' catalog was defined multiple times. 
197
// Use the 'catalog' field or 'catalogs.default', but not both."
198
```
199

200
## Architecture
201

202
The package follows a simple functional architecture:
203

204
- **Main Function**: `getCatalogsFromWorkspaceManifest` handles the primary normalization logic with built-in validation
205
- **Error Handling**: Uses `PnpmError` from @pnpm/error for consistent error reporting
206
- **Type Safety**: Leverages TypeScript interfaces from @pnpm/catalogs.types and @pnpm/workspace.read-manifest
207

208
The normalization process:
209
1. Returns empty object `{}` for null/undefined manifests
210
2. Validates that default catalog isn't defined multiple ways
211
3. Creates normalized structure with `default` property from either source
212
4. Spreads named catalogs from `catalogs` field into the result