0
# @lerna/get-packed
1

2
@lerna/get-packed provides functionality to read and analyze the contents of npm package tarballs created by `npm pack`. It extracts comprehensive metadata including file listings, sizes, checksums, and bundled dependencies from tar archives.
3

4
## Package Information
5

6
- **Package Name**: @lerna/get-packed
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @lerna/get-packed`
10

11
## Core Imports
12

13
```javascript
14
const { getPacked } = require("@lerna/get-packed");
15
```
16

17
ES modules (if your project supports them):
18

19
```javascript
20
import { getPacked } from "@lerna/get-packed";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { getPacked } = require("@lerna/get-packed");
27
const path = require("path");
28

29
// Package metadata (typically from package.json)
30
const pkg = {
31
  name: "my-package",
32
  version: "1.0.0",
33
  bundleDependencies: ["lodash"] // optional
34
};
35

36
// Path to tarball created by npm pack
37
const tarFilePath = "./my-package-1.0.0.tgz";
38

39
// Analyze the tarball
40
getPacked(pkg, tarFilePath).then(result => {
41
  console.log(`Package: ${result.id}`);
42
  console.log(`Size: ${result.size} bytes`);
43
  console.log(`Unpacked size: ${result.unpackedSize} bytes`);
44
  console.log(`Files: ${result.entryCount} entries`);
45
  console.log(`SHA1: ${result.shasum}`);
46
  console.log(`Bundled deps: ${result.bundled.join(", ")}`);
47
  
48
  // List all files
49
  result.files.forEach(file => {
50
    console.log(`${file.path} (${file.size} bytes)`);
51
  });
52
});
53
```
54

55
## Capabilities
56

57
### Tarball Analysis
58

59
Analyzes npm pack tarballs and extracts comprehensive metadata about package contents.
60

61
```javascript { .api }
62
/**
63
 * Analyzes npm pack tarball and returns comprehensive metadata
64
 * @param {Object} pkg - Package metadata object
65
 * @param {string} pkg.name - Package name
66
 * @param {string} pkg.version - Package version  
67
 * @param {string[]} [pkg.bundleDependencies] - List of bundled dependencies
68
 * @param {string[]} [pkg.bundledDependencies] - Alternative name for bundled dependencies
69
 * @param {string} tarFilePath - Path to the tarball file created by npm pack
70
 * @returns {Promise<PackageMetadata>} Promise that resolves to package metadata
71
 */
72
function getPacked(pkg, tarFilePath);
73
```
74

75
**Return Value:**
76

77
```javascript { .api }
78
interface PackageMetadata {
79
  /** Package identifier in format "name@version" */
80
  id: string;
81
  /** Package name */
82
  name: string;
83
  /** Package version */
84
  version: string;
85
  /** Size of the tarball file in bytes */
86
  size: number;
87
  /** Total size of all entries when unpacked */
88
  unpackedSize: number;
89
  /** SHA1 hash of the tarball (hexadecimal) */
90
  shasum: string;
91
  /** SHA512 integrity object from ssri */
92
  integrity: Object;
93
  /** Basename of the tarball file */
94
  filename: string;
95
  /** Array of file objects */
96
  files: FileEntry[];
97
  /** Total number of entries in the tarball */
98
  entryCount: number;
99
  /** Array of bundled dependency names found in node_modules */
100
  bundled: string[];
101
  /** Original tarball file path */
102
  tarFilePath: string;
103
}
104

105
interface FileEntry {
106
  /** Relative path of the file (without package/ prefix) */
107
  path: string;
108
  /** File size in bytes */
109
  size: number;
110
  /** File mode/permissions */
111
  mode: number;
112
}
113
```
114

115
**Usage Examples:**
116

117
Basic tarball analysis:
118
```javascript
119
const { getPacked } = require("@lerna/get-packed");
120

121
const pkg = { name: "example", version: "1.0.0" };
122
const result = await getPacked(pkg, "./example-1.0.0.tgz");
123

124
console.log(`${result.name}@${result.version}`);
125
console.log(`Tarball size: ${result.size} bytes`);
126
console.log(`Contains ${result.files.length} files`);
127
```
128

129
Analyzing bundled dependencies:
130
```javascript
131
const pkg = {
132
  name: "my-app",
133
  version: "2.1.0",
134
  bundleDependencies: ["lodash", "moment"]
135
};
136

137
const result = await getPacked(pkg, "./my-app-2.1.0.tgz");
138
console.log(`Bundled dependencies found: ${result.bundled.join(", ")}`);
139
```
140

141
File inspection:
142
```javascript
143
const result = await getPacked(pkg, tarFilePath);
144

145
// Find large files
146
const largeFiles = result.files.filter(file => file.size > 10000);
147
console.log("Large files:", largeFiles.map(f => `${f.path} (${f.size} bytes)`));
148

149
// Check for specific file types
150
const jsFiles = result.files.filter(file => file.path.endsWith('.js'));
151
console.log(`JavaScript files: ${jsFiles.length}`);
152
```
153

154
**Error Handling:**
155

156
The function returns a rejected Promise if:
157
- The tarball file cannot be read or accessed
158
- The tarball is corrupted or invalid
159
- File system operations fail (e.g., getting file stats)
160

161
Common error scenarios:
162
```javascript
163
try {
164
  const result = await getPacked(pkg, "./nonexistent.tgz");
165
} catch (error) {
166
  if (error.code === 'ENOENT') {
167
    console.error("Tarball file not found");
168
  } else if (error.message.includes('TAR_BAD_ARCHIVE')) {
169
    console.error("Invalid or corrupted tarball");
170
  } else {
171
    console.error("Unexpected error:", error.message);
172
  }
173
}
174
```