Gathering detailed insights and metrics for magic-string
Installations
npm install magic-stringDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS, ESM
Node Version
20.18.0
NPM Version
10.8.2
Score
99.5
Supply Chain
99.2
Quality
90.3
Maintenance
100
Vulnerability
100
License
Releases
Unable to fetch releases
Contributors
53
Unable to fetch Contributors
Languages
2
JavaScript
HTML
JavaScript (99.97%)
HTML (0.03%)
Developer
rich-harris
Download Statistics
Total Downloads
4,371,225,256
Last Day
7,366,582
Last Week
33,297,052
Last Month
146,900,408
Last Year
1,688,842,172
GitHub Statistics
2,448 Stars
571 Commits
116 Forks
15 Watching
11 Branches
53 Contributors
Bundle Size
24.90 kB
Minified
7.63 kB
Minified + Gzipped
Maintainers
4
Package Meta Information
Latest Version
0.30.17
Package Id
magic-string@0.30.17
Unpacked Size
456.51 kB
Size
88.07 kB
File Count
11
NPM Version
10.8.2
Node Version
20.18.0
Publised On
16 Dec 2024
Total Downloads
Cumulative downloads
Total Downloads
4,371,225,256
Last day
-5%
7,366,582
Compared to previous day
Last week
-15.2%
33,297,052
Compared to previous week
Last month
6.3%
146,900,408
Compared to previous month
Last year
41.1%
1,688,842,172
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Versions
magic-string
Suppose you have some source code. You want to make some light modifications to it - replacing a few characters here and there, wrapping it with a header and footer, etc - and ideally you'd like to generate a source map at the end of it. You've thought about using something like recast (which allows you to generate an AST from some JavaScript, manipulate it, and reprint it with a sourcemap without losing your comments and formatting), but it seems like overkill for your needs (or maybe the source code isn't JavaScript).
Your requirements are, frankly, rather niche. But they're requirements that I also have, and for which I made magic-string. It's a small, fast utility for manipulating strings and generating sourcemaps.
Installation
magic-string works in both node.js and browser environments. For node, install with npm:
1npm i magic-string
To use in browser, grab the magic-string.umd.js file and add it to your page:
1<script src="magic-string.umd.js"></script>
(It also works with various module systems, if you prefer that sort of thing - it has a dependency on vlq.)
Usage
These examples assume you're in node.js, or something similar:
1import MagicString from 'magic-string';
2import fs from 'fs';
3
4const s = new MagicString('problems = 99');
5
6s.update(0, 8, 'answer');
7s.toString(); // 'answer = 99'
8
9s.update(11, 13, '42'); // character indices always refer to the original string
10s.toString(); // 'answer = 42'
11
12s.prepend('var ').append(';'); // most methods are chainable
13s.toString(); // 'var answer = 42;'
14
15const map = s.generateMap({
16 source: 'source.js',
17 file: 'converted.js.map',
18 includeContent: true,
19}); // generates a v3 sourcemap
20
21fs.writeFileSync('converted.js', s.toString());
22fs.writeFileSync('converted.js.map', map.toString());You can pass an options argument:
1const s = new MagicString(someCode, {
2 // these options will be used if you later call `bundle.addSource( s )` - see below
3 filename: 'foo.js',
4 indentExclusionRanges: [
5 /*...*/
6 ],
7 // mark source as ignore in DevTools, see below #Bundling
8 ignoreList: false,
9 // adjust the incoming position - see below
10 offset: 0,
11});Properties
s.offset
Sets the offset property to adjust the incoming position for the following APIs: slice, update, overwrite, appendLeft, prependLeft, appendRight, prependRight, move, reset, and remove.
Example usage:
1const s = new MagicString('hello world', { offset: 0 }); 2s.offset = 6; 3s.slice() === 'world';
Methods
s.addSourcemapLocation( index )
Adds the specified character index (with respect to the original string) to sourcemap mappings, if hires is false (see below).
s.append( content )
Appends the specified content to the end of the string. Returns this.
s.appendLeft( index, content )
Appends the specified content at the index in the original string. If a range ending with index is subsequently moved, the insert will be moved with it. Returns this. See also s.prependLeft(...).
s.appendRight( index, content )
Appends the specified content at the index in the original string. If a range starting with index is subsequently moved, the insert will be moved with it. Returns this. See also s.prependRight(...).
s.clone()
Does what you'd expect.
s.generateDecodedMap( options )
Generates a sourcemap object with raw mappings in array form, rather than encoded as a string. See generateMap documentation below for options details. Useful if you need to manipulate the sourcemap further, but most of the time you will use generateMap instead.
s.generateMap( options )
Generates a version 3 sourcemap. All options are, well, optional:
file- the filename where you plan to write the sourcemapsource- the filename of the file containing the original sourceincludeContent- whether to include the original content in the map'ssourcesContentarrayhires- whether the mapping should be high-resolution. Hi-res mappings map every single character, meaning (for example) your devtools will always be able to pinpoint the exact location of function calls and so on. With lo-res mappings, devtools may only be able to identify the correct line - but they're quicker to generate and less bulky. You can also set"boundary"to generate a semi-hi-res mappings segmented per word boundary instead of per character, suitable for string semantics that are separated by words. If sourcemap locations have been specified withs.addSourcemapLocation(), they will be used here.
The returned sourcemap has two (non-enumerable) methods attached for convenience:
toString- returns the equivalent ofJSON.stringify(map)toUrl- returns a DataURI containing the sourcemap. Useful for doing this sort of thing:
1code += '\n//# sourceMappingURL=' + map.toUrl();
s.hasChanged()
Indicates if the string has been changed.
s.indent( prefix[, options] )
Prefixes each line of the string with prefix. If prefix is not supplied, the indentation will be guessed from the original content, falling back to a single tab character. Returns this.
The options argument can have an exclude property, which is an array of [start, end] character ranges. These ranges will be excluded from the indentation - useful for (e.g.) multiline strings.
s.insertLeft( index, content )
DEPRECATED since 0.17 – use s.appendLeft(...) instead
s.insertRight( index, content )
DEPRECATED since 0.17 – use s.prependRight(...) instead
s.isEmpty()
Returns true if the resulting source is empty (disregarding white space).
s.locate( index )
DEPRECATED since 0.10 – see #30
s.locateOrigin( index )
DEPRECATED since 0.10 – see #30
s.move( start, end, index )
Moves the characters from start and end to index. Returns this.
s.overwrite( start, end, content[, options] )
Replaces the characters from start to end with content, along with the appended/prepended content in that range. The same restrictions as s.remove() apply. Returns this.
The fourth argument is optional. It can have a storeName property — if true, the original name will be stored for later inclusion in a sourcemap's names array — and a contentOnly property which determines whether only the content is overwritten, or anything that was appended/prepended to the range as well.
It may be preferred to use s.update(...) instead if you wish to avoid overwriting the appended/prepended content.
s.prepend( content )
Prepends the string with the specified content. Returns this.
s.prependLeft ( index, content )
Same as s.appendLeft(...), except that the inserted content will go before any previous appends or prepends at index
s.prependRight ( index, content )
Same as s.appendRight(...), except that the inserted content will go before any previous appends or prepends at index
s.replace( regexpOrString, substitution )
String replacement with RegExp or string. When using a RegExp, replacer function is also supported. Returns this.
1import MagicString from 'magic-string'; 2 3const s = new MagicString(source); 4 5s.replace('foo', 'bar'); 6s.replace(/foo/g, 'bar'); 7s.replace(/(\w)(\d+)/g, (_, $1, $2) => $1.toUpperCase() + $2);
The differences from String.replace:
- It will always match against the original string
- It mutates the magic string state (use
.clone()to be immutable)
s.replaceAll( regexpOrString, substitution )
Same as s.replace, but replace all matched strings instead of just one.
If regexpOrString is a regex, then it must have the global (g) flag set, or a TypeError is thrown. Matches the behavior of the builtin String.property.replaceAll. Returns this.
s.remove( start, end )
Removes the characters from start to end (of the original string, not the generated string). Removing the same content twice, or making removals that partially overlap, will cause an error. Returns this.
s.reset( start, end )
Resets the characters from start to end (of the original string, not the generated string).
It can be used to restore previously removed characters and discard unwanted changes.
s.slice( start, end )
Returns the content of the generated string that corresponds to the slice between start and end of the original string. Throws error if the indices are for characters that were already removed.
s.snip( start, end )
Returns a clone of s, with all content before the start and end characters of the original string removed.
s.toString()
Returns the generated string.
s.trim([ charType ])
Trims content matching charType (defaults to \s, i.e. whitespace) from the start and end. Returns this.
s.trimStart([ charType ])
Trims content matching charType (defaults to \s, i.e. whitespace) from the start. Returns this.
s.trimEnd([ charType ])
Trims content matching charType (defaults to \s, i.e. whitespace) from the end. Returns this.
s.trimLines()
Removes empty lines from the start and end. Returns this.
s.update( start, end, content[, options] )
Replaces the characters from start to end with content. The same restrictions as s.remove() apply. Returns this.
The fourth argument is optional. It can have a storeName property — if true, the original name will be stored for later inclusion in a sourcemap's names array — and an overwrite property which defaults to false and determines whether anything that was appended/prepended to the range will be overwritten along with the original content.
s.update(start, end, content) is equivalent to s.overwrite(start, end, content, { contentOnly: true }).
Bundling
To concatenate several sources, use MagicString.Bundle:
1const bundle = new MagicString.Bundle();
2
3bundle.addSource({
4 filename: 'foo.js',
5 content: new MagicString('var answer = 42;'),
6});
7
8bundle.addSource({
9 filename: 'bar.js',
10 content: new MagicString('console.log( answer )'),
11});
12
13// Sources can be marked as ignore-listed, which provides a hint to debuggers
14// to not step into this code and also don't show the source files depending
15// on user preferences.
16bundle.addSource({
17 filename: 'some-3rdparty-library.js',
18 content: new MagicString('function myLib(){}'),
19 ignoreList: false, // <--
20});
21
22// Advanced: a source can include an `indentExclusionRanges` property
23// alongside `filename` and `content`. This will be passed to `s.indent()`
24// - see documentation above
25
26bundle
27 .indent() // optionally, pass an indent string, otherwise it will be guessed
28 .prepend('(function () {\n')
29 .append('}());');
30
31bundle.toString();
32// (function () {
33// var answer = 42;
34// console.log( answer );
35// }());
36
37// options are as per `s.generateMap()` above
38const map = bundle.generateMap({
39 file: 'bundle.js',
40 includeContent: true,
41 hires: true,
42});As an alternative syntax, if you a) don't have filename or indentExclusionRanges options, or b) passed those in when you used new MagicString(...), you can simply pass the MagicString instance itself:
1const bundle = new MagicString.Bundle();
2const source = new MagicString(someCode, {
3 filename: 'foo.js',
4});
5
6bundle.addSource(source);License
MIT
No vulnerabilities found.
Reason
no vulnerabilities detected
Reason
no dangerous workflow patterns detected
Reason
license file detected
Details
- Info: : LICENSE:1
Reason
no binaries found in the repo
Reason
update tool detected
Details
- Info: Dependabot detected
Reason
dependency not pinned by hash detected -- score normalized to 9
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/kuchiki-rs/kuchiki/test.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/kuchiki-rs/kuchiki/test.yml/master?enable=pin
- Warn: npmCommand not pinned by hash: .github/workflows/test.yml:36
- Info: Third-party GitHubActions are pinned
- Info: Dockerfile dependencies are pinned
- Info: no insecure (not pinned by hash) dependency downloads found in Dockerfiles
- Info: no insecure (not pinned by hash) dependency downloads found in shell scripts
Reason
GitHub code reviews found for 12 commits out of the last 30 -- score normalized to 4
Details
- Warn: no reviews found for commit: b4603a60a8bc8c1a17c1d789483fdb9f63f152fd
- Warn: no reviews found for commit: 1dbc8109cbb05e9e01464bcd30f8619a416034f5
- Warn: no reviews found for commit: 3fa43434881526d084bf35807d172d9803de76e8
- Warn: no reviews found for commit: 362e72fe745ca314beed11fcc49c2715acf75cba
- Warn: no reviews found for commit: 902541fdff3998e3c957908de10769d2af1a3c70
- Warn: no reviews found for commit: 877b834b61c098de4f923f15ab914c98326577e3
- Warn: no reviews found for commit: aa33b07a2eee748e743f26f95a99ffb1615c0d30
- Warn: no reviews found for commit: 69336fccbb46e721d58faa5c7a0d0b7ed6ee09d2
- Warn: no reviews found for commit: 2815e77dd20ff9f776282420eaacfb4aa9e70cd7
- Warn: no reviews found for commit: de2faf1683c11a16601e9dce6df859a4faa2f203
- Warn: no reviews found for commit: d642aae38fafc3cf7a9effda3d41f6fb79af75b9
- Warn: no reviews found for commit: bce68391375e5e04e7a80e737d0209ada6aa6c1b
- Warn: no reviews found for commit: e04da4bf858ee0ba2d8f2bca3af6050ce4ef1bdf
- Warn: no reviews found for commit: 128e1a24fb5a0fca811d37edfd4d2407b7f5419c
- Warn: no reviews found for commit: 58ad9349f4957a9ed7fa5b3c351c4891bbbbf3ec
- Warn: no reviews found for commit: 4fe1d285ffd29c0b8d232126f91d4d59e5b72951
- Warn: no reviews found for commit: f223b58c4021d05958738899860d598fbed46314
- Warn: no reviews found for commit: 8d58b7cfe80ca38c0c0a78b99e18494f6cbccfd0
Reason
1 commit(s) out of 30 and 1 issue activity out of 30 found in the last 90 days -- score normalized to 1
Reason
no badge detected
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Reason
non read-only tokens detected in GitHub workflows
Details
- Warn: no topLevel permission defined: .github/workflows/test.yml:1: update your workflow using https://app.stepsecurity.io/secureworkflow/kuchiki-rs/kuchiki/test.yml/master?enable=permissions
Reason
security policy file not detected
Reason
project is not fuzzed
Score
5.2
/10
Last Scanned on 2022-08-15
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More