0
# @lerna/log-packed
1

2
@lerna/log-packed is a Node.js utility that formats and displays the JSON output from `npm pack --json` in a human-readable format. It presents tarball information including file listings with sizes, bundled dependencies, and comprehensive package details using formatted columns and Unicode emojis when supported.
3

4
## Package Information
5

6
- **Package Name**: @lerna/log-packed
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @lerna/log-packed`
10
- **Node.js Support**: ^14.15.0 || >=16.0.0
11

12
## Core Imports
13

14
```javascript
15
const { logPacked } = require("@lerna/log-packed");
16
```
17

18
For ES modules (requires bundler or loader):
19

20
```javascript
21
import { logPacked } from "@lerna/log-packed";
22
```
23

24
## Basic Usage
25

26
```javascript
27
const execa = require("execa");
28
const { logPacked } = require("@lerna/log-packed");
29

30
// Get npm pack output and format it
31
execa("npm", ["pack", "--json"]).then(result => {
32
  const tarballs = JSON.parse(result.stdout);
33
  tarballs.forEach(logPacked);
34
});
35
```
36

37
## Capabilities
38

39
### Package Logging
40

41
Formats and logs npm pack JSON output to console with structured, human-readable information.
42

43
```javascript { .api }
44
/**
45
 * Logs formatted npm pack JSON result with tarball details, file contents, and bundled dependencies
46
 * @param {TarballInfo} tarball - Tarball object from npm pack --json output
47
 */
48
function logPacked(tarball);
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
const { logPacked } = require("@lerna/log-packed");
55

56
// Complete tarball info
57
logPacked({
58
  name: "my-package",
59
  version: "1.0.0",
60
  size: 223,
61
  unpackedSize: 396,
62
  shasum: "8f339308bfabffcddd89e379ab76c8fbbc5c429a",
63
  integrity: "sha512-s+D+5+Kovk2mi2Jg+P6egJ6ZBKzMOdRaWAL5S+a4dWnRa6taym9EeEwpwx5ASF1wbLb0Tduv2XqcwFATxxUGVw==",
64
  filename: "my-package-1.0.0.tgz",
65
  files: [
66
    { path: "package.json", size: 396, mode: 420 },
67
    { path: "index.js", size: 1024, mode: 420 }
68
  ],
69
  entryCount: 2,
70
  bundled: ["dependency1", "dependency2"]
71
});
72

73
// Minimal tarball info (gracefully handles missing fields)
74
logPacked({
75
  name: "simple-package",
76
  version: "2.0.0",
77
  filename: "simple-package-2.0.0.tgz"
78
});
79
```
80

81
The function outputs structured information in up to four sections:
82
1. **Package Header**: Package name and version with emoji (📦) if Unicode is supported
83
2. **Tarball Contents**: File listings with sizes (if files present)
84
3. **Bundled Dependencies**: List of bundled dependency names (if present)
85
4. **Tarball Details**: Comprehensive package metadata in formatted columns
86

87
## Types
88

89
```javascript { .api }
90
/**
91
 * Tarball information object from npm pack --json output
92
 */
93
interface TarballInfo {
94
  /** Package name (required) */
95
  name: string;
96
  /** Package version (required) */
97
  version: string;
98
  /** Array of file objects with path and size properties */
99
  files?: FileInfo[];
100
  /** Array of bundled dependency names */
101
  bundled?: string[];
102
  /** Tarball filename */
103
  filename?: string;
104
  /** Package size in bytes */
105
  size?: number;
106
  /** Unpacked size in bytes */
107
  unpackedSize?: number;
108
  /** SHA sum hash */
109
  shasum?: string;
110
  /** Integrity hash */
111
  integrity?: string;
112
  /** Total number of entries in tarball */
113
  entryCount?: number;
114
}
115

116
/**
117
 * File information within a tarball
118
 */
119
interface FileInfo {
120
  /** File path within the package */
121
  path: string;
122
  /** File size in bytes */
123
  size: number;
124
  /** File mode/permissions */
125
  mode?: number;
126
}
127
```
128

129
## Dependencies
130

131
The package uses the following external libraries:
132
- **byte-size** (^7.0.0): For formatting file sizes into human-readable format
133
- **columnify** (^1.6.0): For creating formatted columns in console output
134
- **has-unicode** (^2.0.1): For detecting Unicode support to show emoji decorations
135
- **npmlog** (^6.0.2): For structured logging output to console
136

137
## Error Handling
138

139
The `logPacked` function is designed to handle incomplete tarball objects gracefully:
140
- Missing optional fields are safely ignored using conditional checks
141
- No explicit error throwing for malformed input
142
- Continues execution even with minimal required fields (name, version)
143

144
## Output Format
145

146
The function produces structured console output with:
147
1. **Package Header**: `📦 package-name@version` (or `package: package-name@version` without Unicode)
148
2. **Tarball Contents Section**: File listings with byte-formatted sizes (if files array present)
149
3. **Bundled Dependencies Section**: List of dependency names (if bundled array present) 
150
4. **Tarball Details Section**: Key-value pairs in formatted columns showing package metadata
151

152
Example output:
153
```
154
📦 my-package@1.0.0
155
=== Tarball Contents ===
156
396B package.json
157
1kB  index.js
158
=== Bundled Dependencies ===
159
dependency1
160
dependency2
161
=== Tarball Details ===
162
name:          my-package
163
version:       1.0.0
164
filename:      my-package-1.0.0.tgz
165
package size:  223 B
166
unpacked size: 396 B
167
shasum:        8f339308bfabffcddd89e379ab76c8fbbc5c429a
168
integrity:     sha512-s+d+5+kovk2mi[...]XqcwFATxxUGVw==
169
bundled deps:  2
170
bundled files: 0
171
own files:     2
172
total files:   2
173
174
```