0
# PNPM Catalogs Config
1

2
PNPM Catalogs Config is a TypeScript utility library that provides functionality for parsing and normalizing catalog configurations from pnpm workspace manifest files (pnpm-workspace.yaml). It exports a single main function to handle both implicit default catalogs (via the 'catalog' field) and explicit named catalogs (via the 'catalogs' field), with built-in validation to prevent duplicate default catalog definitions.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/catalogs.config
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pnpm/catalogs.config`
10

11
## Core Imports
12

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

17
For CommonJS:
18

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

23
## Basic Usage
24

25
```typescript
26
import { getCatalogsFromWorkspaceManifest } from "@pnpm/catalogs.config";
27

28
// Process workspace manifest with implicit default catalog
29
const workspaceManifest = {
30
  catalog: {
31
    react: "^18.0.0",
32
    typescript: "^5.0.0"
33
  },
34
  catalogs: {
35
    dev: {
36
      jest: "^29.0.0",
37
      eslint: "^8.0.0"
38
    }
39
  }
40
};
41

42
const normalizedCatalogs = getCatalogsFromWorkspaceManifest(workspaceManifest);
43
// Result: 
44
// {
45
//   default: { react: "^18.0.0", typescript: "^5.0.0" },
46
//   dev: { jest: "^29.0.0", eslint: "^8.0.0" }
47
// }
48

49
// Handle missing workspace manifest
50
const emptyCatalogs = getCatalogsFromWorkspaceManifest(undefined);
51
// Result: {}
52
```
53

54
## Capabilities
55

56
### Catalog Normalization
57

58
Main function that creates a normalized catalogs configuration from pnpm workspace manifest data.
59

60
```typescript { .api }
61
/**
62
 * Creates normalized catalogs config from pnpm workspace manifest data
63
 * @param workspaceManifest - Workspace manifest object with catalog and/or catalogs fields
64
 * @returns Normalized catalogs object
65
 */
66
function getCatalogsFromWorkspaceManifest(
67
  workspaceManifest: Pick<WorkspaceManifest, 'catalog' | 'catalogs'> | undefined
68
): Catalogs;
69
```
70

71
**Behavior:**
72
- Returns empty object `{}` when workspaceManifest is null or undefined
73
- Merges implicit default catalog (from 'catalog' field) with explicit named catalogs (from 'catalogs' field)
74
- Sets default catalog from either manifest.catalog or manifest.catalogs.default
75
- Validates that default catalog is not defined in both places
76
- Throws `PnpmError` with code 'INVALID_CATALOGS_CONFIGURATION' if validation fails
77

78

79
## Types
80

81
```typescript { .api }
82
interface Catalogs {
83
  /**
84
   * The default catalog - can be defined via top-level "catalog" field
85
   * or explicitly named "default" catalog under "catalogs" map
86
   */
87
  readonly default?: Catalog;
88
  
89
  /**
90
   * Named catalogs - additional catalog configurations
91
   */
92
  readonly [catalogName: string]: Catalog | undefined;
93
}
94

95
interface Catalog {
96
  readonly [dependencyName: string]: string | undefined;
97
}
98

99
interface WorkspaceManifest {
100
  /**
101
   * The default catalog - package manifests may refer to dependencies
102
   * through the `catalog:default` or `catalog:` specifier
103
   */
104
  catalog?: WorkspaceCatalog;
105
  
106
  /**
107
   * Named catalogs - package manifests may refer to dependencies
108
   * through the `catalog:<name>` specifier
109
   */
110
  catalogs?: WorkspaceNamedCatalogs;
111
}
112

113
type WorkspaceCatalog = {
114
  readonly [dependencyName: string]: string | undefined;
115
};
116

117
type WorkspaceNamedCatalogs = {
118
  readonly [catalogName: string]: WorkspaceCatalog | undefined;
119
};
120
```
121

122
## Error Handling
123

124
The package throws one specific error when validation fails:
125

126
```typescript { .api }
127
class PnpmError extends Error {
128
  public readonly code: string;
129
  public readonly hint?: string;
130
  constructor(code: string, message: string, opts?: { hint?: string });
131
}
132
```
133

134
**Error Code:**
135
- `ERR_PNPM_INVALID_CATALOGS_CONFIGURATION`: Thrown when both 'catalog' field and 'catalogs.default' field are defined in the workspace manifest
136

137
**Example Error Handling:**
138

139
```typescript
140
import { getCatalogsFromWorkspaceManifest } from "@pnpm/catalogs.config";
141

142
try {
143
  const catalogs = getCatalogsFromWorkspaceManifest({
144
    catalog: { react: "^18.0.0" },
145
    catalogs: {
146
      default: { vue: "^3.0.0" }  // This will cause an error
147
    }
148
  });
149
} catch (error) {
150
  if (error.code === 'ERR_PNPM_INVALID_CATALOGS_CONFIGURATION') {
151
    console.error('Default catalog defined multiple times');
152
  }
153
}
154
```