This document provides comprehensive documentation for the MagicStringStack API. It covers the core MagicStringStack class, its methods, properties, and usage patterns for managing string transformations with commit/rollback capabilities and source map generation.
For implementation details about the internal architecture and proxy pattern, see Implementation Details. For source map handling specifics, see Source Map Generation.
The magic-string-stack library exports a single default class that extends magic-string functionality with version control capabilities:
Sources: src/index.ts1-119
Creates a new MagicStringStack instance with the specified content and optional configuration.
| Parameter | Type | Description |
|---|---|---|
content | string | Initial string content |
options | MagicStringOptions | Optional configuration passed to underlying MagicString instances |
The constructor initializes the internal stack with a single MagicString instance and returns a proxy object that delegates all method calls to the current instance while maintaining chainability.
Sources: src/index.ts22-55
Commits the current state of transformations to the stack. This creates a new MagicString instance from the current string content, resets the .original property and indices, and pushes it to the front of the internal stack.
Behavior:
MagicString instance with current transformed contentoffset property from the current instanceSources: src/index.ts57-68
Rolls back to the previous commit by removing the current instance from the stack and restoring the previous state.
Behavior:
Throws: Error when called with only one commit in the stack
Sources: src/index.ts70-79
Generates a version 3 source map for the current state, merging source maps from all commits in the stack when multiple commits exist.
| Parameter | Type | Description |
|---|---|---|
options | SourceMapOptions | Optional source map generation options |
Returns: SourceMap instance with encoded mappings
Sources: src/index.ts96-101
Generates a source map object with raw mappings in array form rather than encoded as a string. This is useful for further source map manipulation.
Behavior:
MagicString.generateDecodedMap()@ampproject/remapping to merge source maps from all stack layersSources: src/index.ts103-118
Creates a deep copy of the current MagicStringStack instance, including the entire commit stack.
Behavior:
MagicStringStack with current string contentMagicString.clone()Sources: src/index.ts89-94
Returns the original content of the current MagicString instance. This property changes after each commit() call to reflect the committed state.
Sources: src/index.ts81-83
Returns the current transformed string content from the active MagicString instance.
Sources: src/index.ts85-87
MagicStringStack provides access to all MagicString methods through a proxy pattern. These methods maintain their original functionality while supporting method chaining through the proxy:
| Method | Description |
|---|---|
update(start, end, content) | Replace characters from start to end with content |
prepend(content) | Add content to the beginning |
append(content) | Add content to the end |
replace(searchValue, replaceValue) | Replace first occurrence |
replaceAll(searchValue, replaceValue) | Replace all occurrences |
trim() | Remove whitespace from both ends |
trimStart() | Remove whitespace from start |
trimEnd() | Remove whitespace from end |
All MagicString properties are accessible and settable through the proxy, including offset for adjusting source map line/column calculations.
The proxy pattern ensures that:
MagicString methods are available on MagicStringStack instancesSources: src/index.ts29-55 test/index.test.ts95-112
Sources: test/index.test.ts1-127
Refresh this wiki