@medicomind/rolldown-compression 2.3.6 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +36 -5
  3. package/dist/index.cjs +293 -70
  4. package/dist/index.d.cts +60 -9
  5. package/dist/index.d.mts +60 -9
  6. package/dist/index.mjs +293 -70
  7. package/index.js +54 -54
  8. package/package.json +9 -12
package/dist/index.d.cts CHANGED
@@ -36,8 +36,14 @@ type LogLevel = 'silent' | 'error' | 'warn' | 'info';
36
36
  /** Options accepted by {@link compression}. */
37
37
  interface CompressionOptions {
38
38
  /**
39
- * Files to compress. Strings are picomatch globs, RegExps are tested
40
- * against the output file name.
39
+ * Files to compress, matched against the output file name relative to the
40
+ * output directory (always with `/` separators, never a leading `./`).
41
+ * RegExps are tested against that name; strings are globs matched with
42
+ * Node's `path.matchesGlob`, so they follow that dialect (`*` does not
43
+ * cross `/`, `**` does).
44
+ *
45
+ * Note that source maps (`*.map`) are not covered by the default pattern;
46
+ * add `/\.map$/` to `include` if you serve them pre-compressed.
41
47
  * @default /\.(html|xml|css|json|js|mjs|svg|yaml|yml|toml|txt|wasm)$/
42
48
  */
43
49
  include?: string | RegExp | Array<string | RegExp>;
@@ -56,14 +62,28 @@ interface CompressionOptions {
56
62
  /**
57
63
  * Name of the emitted artifact. Tokens: `[path]` (directory, with trailing
58
64
  * slash), `[base]` (file name with extension), `[name]`, `[ext]` (with
59
- * leading dot), `[hash]` (8-char content hash). Function form receives the
60
- * original file name and the canonical algorithm name.
65
+ * leading dot), `[hash]` (8-char hash of the *original*, uncompressed
66
+ * bytes). Function form receives the original file name and the canonical
67
+ * algorithm name.
68
+ *
69
+ * Whichever form is used, the result must be a relative path inside the
70
+ * output directory and must differ from the source name and from every
71
+ * other artifact of the same build; anything else aborts the build.
61
72
  * @default '[path][base]' + per-algorithm extension (.gz / .br / .zst)
62
73
  */
63
74
  filename?: FilenameOption;
64
75
  /**
65
- * Remove the original asset from the bundle once all algorithms have
66
- * processed it.
76
+ * Remove the original asset once every algorithm has produced a variant of
77
+ * it. Files for which no variant was emitted — because `skipIfLargerOrEqual`
78
+ * skipped them, for instance — are always kept, so this can never leave a
79
+ * build without a servable copy of an asset. In `stream` mode it only ever
80
+ * unlinks files this build wrote, never leftovers it merely found in the
81
+ * output directory.
82
+ *
83
+ * Deleting chunks (JS/CSS) only works if whatever serves the build resolves
84
+ * the original request path to the compressed variant; dynamic imports and
85
+ * source map links still point at the original name. The plugin logs a
86
+ * warning the first time it removes a chunk.
67
87
  * @default false
68
88
  */
69
89
  deleteOriginalAssets?: boolean;
@@ -97,7 +117,13 @@ interface CompressionOptions {
97
117
  * @default false
98
118
  */
99
119
  stream?: boolean;
100
- /** @default 'info' */
120
+ /**
121
+ * `'info'` logs the per-build summary through `this.info` and per-file
122
+ * detail through `this.debug` (the bundler's own log level decides whether
123
+ * debug output is shown); `'warn'` keeps only warnings; `'error'` and
124
+ * `'silent'` leave build-aborting errors as the only output.
125
+ * @default 'info'
126
+ */
101
127
  logLevel?: LogLevel;
102
128
  /**
103
129
  * The plugin is a no-op in watch/dev mode unless this is set to `true`.
@@ -115,6 +141,31 @@ declare function defineAlgorithm(name: 'gzip' | 'gz', options?: GzipOptions): De
115
141
  declare function defineAlgorithm(name: 'brotli' | 'br' | 'brotliCompress', options?: BrotliOptions): DefineAlgorithmResult;
116
142
  declare function defineAlgorithm(name: 'zstd' | 'zstandard', options?: ZstdOptions): DefineAlgorithmResult;
117
143
  //#endregion
144
+ //#region ts/plugin.d.ts
145
+ /**
146
+ * The plugin's `api`, for the documented inter-plugin communication channel:
147
+ * another plugin can look this one up by name and learn which artifacts it
148
+ * produces, e.g. to wire up a dev-server middleware that serves them.
149
+ */
150
+ interface CompressionPluginApi {
151
+ /** Name of the package this plugin ships in. */
152
+ readonly packageName: string;
153
+ /** Canonical algorithms this instance runs, in order. */
154
+ readonly algorithms: readonly CanonicalAlgorithm[];
155
+ /** Default extensions for those algorithms (`.gz`, `.br`, `.zst`). */
156
+ readonly extensions: readonly string[];
157
+ /** Artifact names emitted for the most recently generated output. */
158
+ emittedFileNames(): string[];
159
+ }
160
+ /**
161
+ * Fields Vite reads off a plugin object. They are not part of rolldown's
162
+ * `Plugin` type — plain rolldown ignores them.
163
+ */
164
+ interface VitePluginFields {
165
+ apply?: 'build' | 'serve';
166
+ }
167
+ type CompressionPlugin = Plugin<CompressionPluginApi> & VitePluginFields;
168
+ //#endregion
118
169
  //#region ts/index.d.ts
119
170
  /**
120
171
  * Create the compression plugin.
@@ -135,6 +186,6 @@ declare function defineAlgorithm(name: 'zstd' | 'zstandard', options?: ZstdOptio
135
186
  * ],
136
187
  * })
137
188
  */
138
- declare function compression(options?: CompressionOptions): Plugin;
189
+ declare function compression(options?: CompressionOptions): CompressionPlugin;
139
190
  //#endregion
140
- export { type AlgorithmName, type BrotliOptions, type CanonicalAlgorithm, type CompressionOptions, type DefineAlgorithmResult, type FilenameOption, type GzipOptions, type LogLevel, type ZstdOptions, compression, defineAlgorithm };
191
+ export { type AlgorithmName, type BrotliOptions, type CanonicalAlgorithm, type CompressionOptions, type CompressionPlugin, type CompressionPluginApi, type DefineAlgorithmResult, type FilenameOption, type GzipOptions, type LogLevel, type ZstdOptions, compression, defineAlgorithm };
package/dist/index.d.mts CHANGED
@@ -36,8 +36,14 @@ type LogLevel = 'silent' | 'error' | 'warn' | 'info';
36
36
  /** Options accepted by {@link compression}. */
37
37
  interface CompressionOptions {
38
38
  /**
39
- * Files to compress. Strings are picomatch globs, RegExps are tested
40
- * against the output file name.
39
+ * Files to compress, matched against the output file name relative to the
40
+ * output directory (always with `/` separators, never a leading `./`).
41
+ * RegExps are tested against that name; strings are globs matched with
42
+ * Node's `path.matchesGlob`, so they follow that dialect (`*` does not
43
+ * cross `/`, `**` does).
44
+ *
45
+ * Note that source maps (`*.map`) are not covered by the default pattern;
46
+ * add `/\.map$/` to `include` if you serve them pre-compressed.
41
47
  * @default /\.(html|xml|css|json|js|mjs|svg|yaml|yml|toml|txt|wasm)$/
42
48
  */
43
49
  include?: string | RegExp | Array<string | RegExp>;
@@ -56,14 +62,28 @@ interface CompressionOptions {
56
62
  /**
57
63
  * Name of the emitted artifact. Tokens: `[path]` (directory, with trailing
58
64
  * slash), `[base]` (file name with extension), `[name]`, `[ext]` (with
59
- * leading dot), `[hash]` (8-char content hash). Function form receives the
60
- * original file name and the canonical algorithm name.
65
+ * leading dot), `[hash]` (8-char hash of the *original*, uncompressed
66
+ * bytes). Function form receives the original file name and the canonical
67
+ * algorithm name.
68
+ *
69
+ * Whichever form is used, the result must be a relative path inside the
70
+ * output directory and must differ from the source name and from every
71
+ * other artifact of the same build; anything else aborts the build.
61
72
  * @default '[path][base]' + per-algorithm extension (.gz / .br / .zst)
62
73
  */
63
74
  filename?: FilenameOption;
64
75
  /**
65
- * Remove the original asset from the bundle once all algorithms have
66
- * processed it.
76
+ * Remove the original asset once every algorithm has produced a variant of
77
+ * it. Files for which no variant was emitted — because `skipIfLargerOrEqual`
78
+ * skipped them, for instance — are always kept, so this can never leave a
79
+ * build without a servable copy of an asset. In `stream` mode it only ever
80
+ * unlinks files this build wrote, never leftovers it merely found in the
81
+ * output directory.
82
+ *
83
+ * Deleting chunks (JS/CSS) only works if whatever serves the build resolves
84
+ * the original request path to the compressed variant; dynamic imports and
85
+ * source map links still point at the original name. The plugin logs a
86
+ * warning the first time it removes a chunk.
67
87
  * @default false
68
88
  */
69
89
  deleteOriginalAssets?: boolean;
@@ -97,7 +117,13 @@ interface CompressionOptions {
97
117
  * @default false
98
118
  */
99
119
  stream?: boolean;
100
- /** @default 'info' */
120
+ /**
121
+ * `'info'` logs the per-build summary through `this.info` and per-file
122
+ * detail through `this.debug` (the bundler's own log level decides whether
123
+ * debug output is shown); `'warn'` keeps only warnings; `'error'` and
124
+ * `'silent'` leave build-aborting errors as the only output.
125
+ * @default 'info'
126
+ */
101
127
  logLevel?: LogLevel;
102
128
  /**
103
129
  * The plugin is a no-op in watch/dev mode unless this is set to `true`.
@@ -115,6 +141,31 @@ declare function defineAlgorithm(name: 'gzip' | 'gz', options?: GzipOptions): De
115
141
  declare function defineAlgorithm(name: 'brotli' | 'br' | 'brotliCompress', options?: BrotliOptions): DefineAlgorithmResult;
116
142
  declare function defineAlgorithm(name: 'zstd' | 'zstandard', options?: ZstdOptions): DefineAlgorithmResult;
117
143
  //#endregion
144
+ //#region ts/plugin.d.ts
145
+ /**
146
+ * The plugin's `api`, for the documented inter-plugin communication channel:
147
+ * another plugin can look this one up by name and learn which artifacts it
148
+ * produces, e.g. to wire up a dev-server middleware that serves them.
149
+ */
150
+ interface CompressionPluginApi {
151
+ /** Name of the package this plugin ships in. */
152
+ readonly packageName: string;
153
+ /** Canonical algorithms this instance runs, in order. */
154
+ readonly algorithms: readonly CanonicalAlgorithm[];
155
+ /** Default extensions for those algorithms (`.gz`, `.br`, `.zst`). */
156
+ readonly extensions: readonly string[];
157
+ /** Artifact names emitted for the most recently generated output. */
158
+ emittedFileNames(): string[];
159
+ }
160
+ /**
161
+ * Fields Vite reads off a plugin object. They are not part of rolldown's
162
+ * `Plugin` type — plain rolldown ignores them.
163
+ */
164
+ interface VitePluginFields {
165
+ apply?: 'build' | 'serve';
166
+ }
167
+ type CompressionPlugin = Plugin<CompressionPluginApi> & VitePluginFields;
168
+ //#endregion
118
169
  //#region ts/index.d.ts
119
170
  /**
120
171
  * Create the compression plugin.
@@ -135,6 +186,6 @@ declare function defineAlgorithm(name: 'zstd' | 'zstandard', options?: ZstdOptio
135
186
  * ],
136
187
  * })
137
188
  */
138
- declare function compression(options?: CompressionOptions): Plugin;
189
+ declare function compression(options?: CompressionOptions): CompressionPlugin;
139
190
  //#endregion
140
- export { type AlgorithmName, type BrotliOptions, type CanonicalAlgorithm, type CompressionOptions, type DefineAlgorithmResult, type FilenameOption, type GzipOptions, type LogLevel, type ZstdOptions, compression, defineAlgorithm };
191
+ export { type AlgorithmName, type BrotliOptions, type CanonicalAlgorithm, type CompressionOptions, type CompressionPlugin, type CompressionPluginApi, type DefineAlgorithmResult, type FilenameOption, type GzipOptions, type LogLevel, type ZstdOptions, compression, defineAlgorithm };