初始化

This commit is contained in:
yziiy
2025-08-11 11:06:07 +08:00
parent 083bc37c00
commit 5607d11395
19772 changed files with 3108723 additions and 18 deletions

View File

@@ -0,0 +1,21 @@
The MIT License (MIT)
Copyright (c) 2018-present, Yuxi (Evan) You
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

View File

@@ -0,0 +1,121 @@
# @vue/reactivity-transform
> ⚠️ This is experimental and currently only provided for testing and feedback. It may break during patches or even be removed. Use at your own risk!
>
> Follow https://github.com/vuejs/rfcs/discussions/369 for details and updates.
## Basic Rules
- Ref-creating APIs have `$`-prefixed versions that create reactive variables instead. They also do not need to be explicitly imported. These include:
- `ref`
- `computed`
- `shallowRef`
- `customRef`
- `toRef`
- `$()` can be used to destructure an object into reactive variables, or turn existing refs into reactive variables
- `$$()` to "escape" the transform, which allows access to underlying refs
```js
import { watchEffect } from 'vue'
// bind ref as a variable
let count = $ref(0)
watchEffect(() => {
// no need for .value
console.log(count)
})
// assignments are reactive
count++
// get the actual ref
console.log($$(count)) // { value: 1 }
```
Macros can be optionally imported to make it more explicit:
```js
// not necessary, but also works
import { $, $ref } from 'vue/macros'
let count = $ref(0)
const { x, y } = $(useMouse())
```
### Global Types
To enable types for the macros globally, include the following in a `.d.ts` file:
```ts
/// <reference types="vue/macros-global" />
```
## API
This package is the lower-level transform that can be used standalone. Higher-level tooling (e.g. `@vitejs/plugin-vue` and `vue-loader`) will provide integration via options.
### `shouldTransform`
Can be used to do a cheap check to determine whether full transform should be performed.
```js
import { shouldTransform } from '@vue/reactivity-transform'
shouldTransform(`let a = ref(0)`) // false
shouldTransform(`let a = $ref(0)`) // true
```
### `transform`
```js
import { transform } from '@vue/reactivity-transform'
const src = `let a = $ref(0); a++`
const {
code, // import { ref as _ref } from 'vue'; let a = (ref(0)); a.value++"
map
} = transform(src, {
filename: 'foo.ts',
sourceMap: true,
// @babel/parser plugins to enable.
// 'typescript' and 'jsx' will be auto-inferred from filename if provided,
// so in most cases explicit parserPlugins are not necessary
parserPlugins: [
/* ... */
]
})
```
**Options**
```ts
interface RefTransformOptions {
filename?: string
sourceMap?: boolean // default: false
parserPlugins?: ParserPlugin[]
importHelpersFrom?: string // default: "vue"
}
```
### `transformAST`
Transform with an existing Babel AST + MagicString instance. This is used internally by `@vue/compiler-sfc` to avoid double parse/transform cost.
```js
import { transformAST } from '@vue/reactivity-transform'
import { parse } from '@babel/parser'
import MagicString from 'magic-string'
const src = `let a = $ref(0); a++`
const ast = parse(src, { sourceType: 'module' })
const s = new MagicString(src)
const {
rootRefs, // ['a']
importedHelpers // ['ref']
} = transformAST(ast, s)
console.log(s.toString()) // let a = _ref(0); a.value++
```

View File

@@ -0,0 +1,606 @@
'use strict';
Object.defineProperty(exports, '__esModule', { value: true });
var MagicString = require('magic-string');
var estreeWalker = require('estree-walker');
var compilerCore = require('@vue/compiler-core');
var parser = require('@babel/parser');
var shared = require('@vue/shared');
const CONVERT_SYMBOL = '$';
const ESCAPE_SYMBOL = '$$';
const IMPORT_SOURCE = 'vue/macros';
const shorthands = ['ref', 'computed', 'shallowRef', 'toRef', 'customRef'];
const transformCheckRE = /[^\w]\$(?:\$|ref|computed|shallowRef)?\s*(\(|\<)/;
function shouldTransform(src) {
return transformCheckRE.test(src);
}
function transform(src, { filename, sourceMap, parserPlugins, importHelpersFrom = 'vue' } = {}) {
const plugins = parserPlugins || [];
if (filename) {
if (/\.tsx?$/.test(filename)) {
plugins.push('typescript');
}
if (filename.endsWith('x')) {
plugins.push('jsx');
}
}
const ast = parser.parse(src, {
sourceType: 'module',
plugins
});
const s = new MagicString(src);
const res = transformAST(ast.program, s, 0);
// inject helper imports
if (res.importedHelpers.length) {
s.prepend(`import { ${res.importedHelpers
.map(h => `${h} as _${h}`)
.join(', ')} } from '${importHelpersFrom}'\n`);
}
return {
...res,
code: s.toString(),
map: sourceMap
? s.generateMap({
source: filename,
hires: true,
includeContent: true
})
: null
};
}
function transformAST(ast, s, offset = 0, knownRefs, knownProps) {
// TODO remove when out of experimental
warnExperimental();
const userImports = Object.create(null);
for (const node of ast.body) {
if (node.type !== 'ImportDeclaration')
continue;
walkImportDeclaration(node);
}
// macro import handling
let convertSymbol;
let escapeSymbol;
for (const { local, imported, source, specifier } of Object.values(userImports)) {
if (source === IMPORT_SOURCE) {
if (imported === ESCAPE_SYMBOL) {
escapeSymbol = local;
}
else if (imported === CONVERT_SYMBOL) {
convertSymbol = local;
}
else if (imported !== local) {
error(`macro imports for ref-creating methods do not support aliasing.`, specifier);
}
}
}
// default symbol
if (!convertSymbol && !userImports[CONVERT_SYMBOL]) {
convertSymbol = CONVERT_SYMBOL;
}
if (!escapeSymbol && !userImports[ESCAPE_SYMBOL]) {
escapeSymbol = ESCAPE_SYMBOL;
}
const importedHelpers = new Set();
const rootScope = {};
const scopeStack = [rootScope];
let currentScope = rootScope;
let escapeScope; // inside $$()
const excludedIds = new WeakSet();
const parentStack = [];
const propsLocalToPublicMap = Object.create(null);
if (knownRefs) {
for (const key of knownRefs) {
rootScope[key] = {};
}
}
if (knownProps) {
for (const key in knownProps) {
const { local, isConst } = knownProps[key];
rootScope[local] = {
isProp: true,
isConst: !!isConst
};
propsLocalToPublicMap[local] = key;
}
}
function walkImportDeclaration(node) {
const source = node.source.value;
if (source === IMPORT_SOURCE) {
s.remove(node.start + offset, node.end + offset);
}
for (const specifier of node.specifiers) {
const local = specifier.local.name;
const imported = (specifier.type === 'ImportSpecifier' &&
specifier.imported.type === 'Identifier' &&
specifier.imported.name) ||
'default';
userImports[local] = {
source,
local,
imported,
specifier
};
}
}
function isRefCreationCall(callee) {
if (!convertSymbol || currentScope[convertSymbol] !== undefined) {
return false;
}
if (callee === convertSymbol) {
return convertSymbol;
}
if (callee[0] === '$' && shorthands.includes(callee.slice(1))) {
return callee;
}
return false;
}
function error(msg, node) {
const e = new Error(msg);
e.node = node;
throw e;
}
function helper(msg) {
importedHelpers.add(msg);
return `_${msg}`;
}
function registerBinding(id, binding) {
excludedIds.add(id);
if (currentScope) {
currentScope[id.name] = binding ? binding : false;
}
else {
error('registerBinding called without active scope, something is wrong.', id);
}
}
const registerRefBinding = (id, isConst = false) => registerBinding(id, { isConst });
let tempVarCount = 0;
function genTempVar() {
return `__$temp_${++tempVarCount}`;
}
function snip(node) {
return s.original.slice(node.start + offset, node.end + offset);
}
function walkScope(node, isRoot = false) {
for (const stmt of node.body) {
if (stmt.type === 'VariableDeclaration') {
walkVariableDeclaration(stmt, isRoot);
}
else if (stmt.type === 'FunctionDeclaration' ||
stmt.type === 'ClassDeclaration') {
if (stmt.declare || !stmt.id)
continue;
registerBinding(stmt.id);
}
else if ((stmt.type === 'ForOfStatement' || stmt.type === 'ForInStatement') &&
stmt.left.type === 'VariableDeclaration') {
walkVariableDeclaration(stmt.left);
}
else if (stmt.type === 'ExportNamedDeclaration' &&
stmt.declaration &&
stmt.declaration.type === 'VariableDeclaration') {
walkVariableDeclaration(stmt.declaration, isRoot);
}
else if (stmt.type === 'LabeledStatement' &&
stmt.body.type === 'VariableDeclaration') {
walkVariableDeclaration(stmt.body, isRoot);
}
}
}
function walkVariableDeclaration(stmt, isRoot = false) {
if (stmt.declare) {
return;
}
for (const decl of stmt.declarations) {
let refCall;
const isCall = decl.init &&
decl.init.type === 'CallExpression' &&
decl.init.callee.type === 'Identifier';
if (isCall &&
(refCall = isRefCreationCall(decl.init.callee.name))) {
processRefDeclaration(refCall, decl.id, decl.init, stmt.kind === 'const');
}
else {
const isProps = isRoot && isCall && decl.init.callee.name === 'defineProps';
for (const id of compilerCore.extractIdentifiers(decl.id)) {
if (isProps) {
// for defineProps destructure, only exclude them since they
// are already passed in as knownProps
excludedIds.add(id);
}
else {
registerBinding(id);
}
}
}
}
}
function processRefDeclaration(method, id, call, isConst) {
excludedIds.add(call.callee);
if (method === convertSymbol) {
// $
// remove macro
s.remove(call.callee.start + offset, call.callee.end + offset);
if (id.type === 'Identifier') {
// single variable
registerRefBinding(id, isConst);
}
else if (id.type === 'ObjectPattern') {
processRefObjectPattern(id, call, isConst);
}
else if (id.type === 'ArrayPattern') {
processRefArrayPattern(id, call, isConst);
}
}
else {
// shorthands
if (id.type === 'Identifier') {
registerRefBinding(id, isConst);
// replace call
s.overwrite(call.start + offset, call.start + method.length + offset, helper(method.slice(1)));
}
else {
error(`${method}() cannot be used with destructure patterns.`, call);
}
}
}
function processRefObjectPattern(pattern, call, isConst, tempVar, path = []) {
if (!tempVar) {
tempVar = genTempVar();
// const { x } = $(useFoo()) --> const __$temp_1 = useFoo()
s.overwrite(pattern.start + offset, pattern.end + offset, tempVar);
}
let nameId;
for (const p of pattern.properties) {
let key;
let defaultValue;
if (p.type === 'ObjectProperty') {
if (p.key.start === p.value.start) {
// shorthand { foo }
nameId = p.key;
if (p.value.type === 'Identifier') {
// avoid shorthand value identifier from being processed
excludedIds.add(p.value);
}
else if (p.value.type === 'AssignmentPattern' &&
p.value.left.type === 'Identifier') {
// { foo = 1 }
excludedIds.add(p.value.left);
defaultValue = p.value.right;
}
}
else {
key = p.computed ? p.key : p.key.name;
if (p.value.type === 'Identifier') {
// { foo: bar }
nameId = p.value;
}
else if (p.value.type === 'ObjectPattern') {
processRefObjectPattern(p.value, call, isConst, tempVar, [
...path,
key
]);
}
else if (p.value.type === 'ArrayPattern') {
processRefArrayPattern(p.value, call, isConst, tempVar, [
...path,
key
]);
}
else if (p.value.type === 'AssignmentPattern') {
if (p.value.left.type === 'Identifier') {
// { foo: bar = 1 }
nameId = p.value.left;
defaultValue = p.value.right;
}
else if (p.value.left.type === 'ObjectPattern') {
processRefObjectPattern(p.value.left, call, isConst, tempVar, [
...path,
[key, p.value.right]
]);
}
else if (p.value.left.type === 'ArrayPattern') {
processRefArrayPattern(p.value.left, call, isConst, tempVar, [
...path,
[key, p.value.right]
]);
}
else ;
}
}
}
else {
// rest element { ...foo }
error(`reactivity destructure does not support rest elements.`, p);
}
if (nameId) {
registerRefBinding(nameId, isConst);
// inject toRef() after original replaced pattern
const source = pathToString(tempVar, path);
const keyStr = shared.isString(key)
? `'${key}'`
: key
? snip(key)
: `'${nameId.name}'`;
const defaultStr = defaultValue ? `, ${snip(defaultValue)}` : ``;
s.appendLeft(call.end + offset, `,\n ${nameId.name} = ${helper('toRef')}(${source}, ${keyStr}${defaultStr})`);
}
}
if (nameId) {
s.appendLeft(call.end + offset, ';');
}
}
function processRefArrayPattern(pattern, call, isConst, tempVar, path = []) {
if (!tempVar) {
// const [x] = $(useFoo()) --> const __$temp_1 = useFoo()
tempVar = genTempVar();
s.overwrite(pattern.start + offset, pattern.end + offset, tempVar);
}
let nameId;
for (let i = 0; i < pattern.elements.length; i++) {
const e = pattern.elements[i];
if (!e)
continue;
let defaultValue;
if (e.type === 'Identifier') {
// [a] --> [__a]
nameId = e;
}
else if (e.type === 'AssignmentPattern') {
// [a = 1]
nameId = e.left;
defaultValue = e.right;
}
else if (e.type === 'RestElement') {
// [...a]
error(`reactivity destructure does not support rest elements.`, e);
}
else if (e.type === 'ObjectPattern') {
processRefObjectPattern(e, call, isConst, tempVar, [...path, i]);
}
else if (e.type === 'ArrayPattern') {
processRefArrayPattern(e, call, isConst, tempVar, [...path, i]);
}
if (nameId) {
registerRefBinding(nameId, isConst);
// inject toRef() after original replaced pattern
const source = pathToString(tempVar, path);
const defaultStr = defaultValue ? `, ${snip(defaultValue)}` : ``;
s.appendLeft(call.end + offset, `,\n ${nameId.name} = ${helper('toRef')}(${source}, ${i}${defaultStr})`);
}
}
if (nameId) {
s.appendLeft(call.end + offset, ';');
}
}
function pathToString(source, path) {
if (path.length) {
for (const seg of path) {
if (shared.isArray(seg)) {
source = `(${source}${segToString(seg[0])} || ${snip(seg[1])})`;
}
else {
source += segToString(seg);
}
}
}
return source;
}
function segToString(seg) {
if (typeof seg === 'number') {
return `[${seg}]`;
}
else if (typeof seg === 'string') {
return `.${seg}`;
}
else {
return snip(seg);
}
}
function rewriteId(scope, id, parent, parentStack) {
if (shared.hasOwn(scope, id.name)) {
const binding = scope[id.name];
if (binding) {
if (binding.isConst &&
((parent.type === 'AssignmentExpression' && id === parent.left) ||
parent.type === 'UpdateExpression')) {
error(`Assignment to constant variable.`, id);
}
const { isProp } = binding;
if (compilerCore.isStaticProperty(parent) && parent.shorthand) {
// let binding used in a property shorthand
// skip for destructure patterns
if (!parent.inPattern ||
compilerCore.isInDestructureAssignment(parent, parentStack)) {
if (isProp) {
if (escapeScope) {
// prop binding in $$()
// { prop } -> { prop: __props_prop }
registerEscapedPropBinding(id);
s.appendLeft(id.end + offset, `: __props_${propsLocalToPublicMap[id.name]}`);
}
else {
// { prop } -> { prop: __props.prop }
s.appendLeft(id.end + offset, `: ${shared.genPropsAccessExp(propsLocalToPublicMap[id.name])}`);
}
}
else {
// { foo } -> { foo: foo.value }
s.appendLeft(id.end + offset, `: ${id.name}.value`);
}
}
}
else {
if (isProp) {
if (escapeScope) {
// x --> __props_x
registerEscapedPropBinding(id);
s.overwrite(id.start + offset, id.end + offset, `__props_${propsLocalToPublicMap[id.name]}`);
}
else {
// x --> __props.x
s.overwrite(id.start + offset, id.end + offset, shared.genPropsAccessExp(propsLocalToPublicMap[id.name]));
}
}
else {
// x --> x.value
s.appendLeft(id.end + offset, '.value');
}
}
}
return true;
}
return false;
}
const propBindingRefs = {};
function registerEscapedPropBinding(id) {
if (!propBindingRefs.hasOwnProperty(id.name)) {
propBindingRefs[id.name] = true;
const publicKey = propsLocalToPublicMap[id.name];
s.prependRight(offset, `const __props_${publicKey} = ${helper(`toRef`)}(__props, '${publicKey}');\n`);
}
}
// check root scope first
walkScope(ast, true);
estreeWalker.walk(ast, {
enter(node, parent) {
parent && parentStack.push(parent);
// function scopes
if (compilerCore.isFunctionType(node)) {
scopeStack.push((currentScope = {}));
compilerCore.walkFunctionParams(node, registerBinding);
if (node.body.type === 'BlockStatement') {
walkScope(node.body);
}
return;
}
// catch param
if (node.type === 'CatchClause') {
scopeStack.push((currentScope = {}));
if (node.param && node.param.type === 'Identifier') {
registerBinding(node.param);
}
walkScope(node.body);
return;
}
// non-function block scopes
if (node.type === 'BlockStatement' && !compilerCore.isFunctionType(parent)) {
scopeStack.push((currentScope = {}));
walkScope(node);
return;
}
// skip type nodes
if (parent &&
parent.type.startsWith('TS') &&
parent.type !== 'TSAsExpression' &&
parent.type !== 'TSNonNullExpression' &&
parent.type !== 'TSTypeAssertion') {
return this.skip();
}
if (node.type === 'Identifier') {
const binding = rootScope[node.name];
if (
// if inside $$(), skip unless this is a destructured prop binding
!(escapeScope && (!binding || !binding.isProp)) &&
compilerCore.isReferencedIdentifier(node, parent, parentStack) &&
!excludedIds.has(node)) {
// walk up the scope chain to check if id should be appended .value
let i = scopeStack.length;
while (i--) {
if (rewriteId(scopeStack[i], node, parent, parentStack)) {
return;
}
}
}
}
if (node.type === 'CallExpression' && node.callee.type === 'Identifier') {
const callee = node.callee.name;
const refCall = isRefCreationCall(callee);
if (refCall && (!parent || parent.type !== 'VariableDeclarator')) {
return error(`${refCall} can only be used as the initializer of ` +
`a variable declaration.`, node);
}
if (escapeSymbol &&
currentScope[escapeSymbol] === undefined &&
callee === escapeSymbol) {
escapeScope = node;
s.remove(node.callee.start + offset, node.callee.end + offset);
if ((parent === null || parent === void 0 ? void 0 : parent.type) === 'ExpressionStatement') {
// edge case where the call expression is an expression statement
// if its own - prepend semicolon to avoid it being parsed as
// function invocation of previous line
let i = (node.leadingComments
? node.leadingComments[0].start
: node.start) + offset;
while (i--) {
const char = s.original.charAt(i);
if (char === '\n') {
// only insert semi if it's actually the fisrt thign after
// newline
s.prependRight(node.start + offset, ';');
break;
}
else if (!/\s/.test(char)) {
break;
}
}
}
}
// TODO remove when out of experimental
if (callee === '$raw') {
error(`$raw() has been replaced by $$(). ` +
`See ${RFC_LINK} for latest updates.`, node);
}
if (callee === '$fromRef') {
error(`$fromRef() has been replaced by $(). ` +
`See ${RFC_LINK} for latest updates.`, node);
}
}
},
leave(node, parent) {
parent && parentStack.pop();
if ((node.type === 'BlockStatement' && !compilerCore.isFunctionType(parent)) ||
compilerCore.isFunctionType(node)) {
scopeStack.pop();
currentScope = scopeStack[scopeStack.length - 1] || null;
}
if (node === escapeScope) {
escapeScope = undefined;
}
}
});
return {
rootRefs: Object.keys(rootScope).filter(key => {
const binding = rootScope[key];
return binding && !binding.isProp;
}),
importedHelpers: [...importedHelpers]
};
}
const RFC_LINK = `https://github.com/vuejs/rfcs/discussions/369`;
const hasWarned = {};
function warnExperimental() {
// eslint-disable-next-line
if (typeof window !== 'undefined') {
return;
}
warnOnce(`Reactivity transform is an experimental feature.\n` +
`Experimental features may change behavior between patch versions.\n` +
`It is recommended to pin your vue dependencies to exact versions to avoid breakage.\n` +
`You can follow the proposal's status at ${RFC_LINK}.`);
}
function warnOnce(msg) {
const isNodeProd = typeof process !== 'undefined' && process.env.NODE_ENV === 'production';
if (!isNodeProd && !false && !hasWarned[msg]) {
hasWarned[msg] = true;
warn(msg);
}
}
function warn(msg) {
console.warn(`\x1b[1m\x1b[33m[@vue/reactivity-transform]\x1b[0m\x1b[33m ${msg}\x1b[0m\n`);
}
exports.shouldTransform = shouldTransform;
exports.transform = transform;
exports.transformAST = transformAST;

View File

@@ -0,0 +1,44 @@
import { ImportDefaultSpecifier } from '@babel/types';
import { ImportNamespaceSpecifier } from '@babel/types';
import { ImportSpecifier } from '@babel/types';
import MagicString from 'magic-string';
import { ParserPlugin } from '@babel/parser';
import { Program } from '@babel/types';
import { SourceMap } from 'magic-string';
export declare interface ImportBinding {
local: string;
imported: string;
source: string;
specifier: ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier;
}
export declare interface RefTransformOptions {
filename?: string;
sourceMap?: boolean;
parserPlugins?: ParserPlugin[];
importHelpersFrom?: string;
}
export declare interface RefTransformResults {
code: string;
map: SourceMap | null;
rootRefs: string[];
importedHelpers: string[];
}
export declare function shouldTransform(src: string): boolean;
export declare function transform(src: string, { filename, sourceMap, parserPlugins, importHelpersFrom }?: RefTransformOptions): RefTransformResults;
export declare function transformAST(ast: Program, s: MagicString, offset?: number, knownRefs?: string[], knownProps?: Record<string, // public prop key
{
local: string;
default?: any;
isConst?: boolean;
}>): {
rootRefs: string[];
importedHelpers: string[];
};
export { }

View File

@@ -0,0 +1,7 @@
Copyright 2018 Rich Harris
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

View File

@@ -0,0 +1,252 @@
# magic-string
<a href="https://travis-ci.org/Rich-Harris/magic-string">
<img src="http://img.shields.io/travis/Rich-Harris/magic-string.svg"
alt="build status">
</a>
<a href="https://npmjs.org/package/magic-string">
<img src="https://img.shields.io/npm/v/magic-string.svg"
alt="npm version">
</a>
<a href="https://github.com/Rich-Harris/magic-string/blob/master/LICENSE.md">
<img src="https://img.shields.io/npm/l/magic-string.svg"
alt="license">
</a>
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](https://github.com/benjamn/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:
```bash
npm i magic-string
```
To use in browser, grab the [magic-string.umd.js](https://unpkg.com/magic-string/dist/magic-string.umd.js) file and add it to your page:
```html
<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](https://github.com/Rich-Harris/vlq).)
## Usage
These examples assume you're in node.js, or something similar:
```js
import MagicString from 'magic-string';
import fs from 'fs'
const s = new MagicString('problems = 99');
s.overwrite(0, 8, 'answer');
s.toString(); // 'answer = 99'
s.overwrite(11, 13, '42'); // character indices always refer to the original string
s.toString(); // 'answer = 42'
s.prepend('var ').append(';'); // most methods are chainable
s.toString(); // 'var answer = 42;'
const map = s.generateMap({
source: 'source.js',
file: 'converted.js.map',
includeContent: true
}); // generates a v3 sourcemap
fs.writeFileSync('converted.js', s.toString());
fs.writeFileSync('converted.js.map', map.toString());
```
You can pass an options argument:
```js
const s = new MagicString(someCode, {
// both these options will be used if you later
// call `bundle.addSource( s )` - see below
filename: 'foo.js',
indentExclusionRanges: [/*...*/]
});
```
## 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](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit). All options are, well, optional:
* `file` - the filename where you plan to write the sourcemap
* `source` - the filename of the file containing the original source
* `includeContent` - whether to include the original content in the map's `sourcesContent` array
* `hires` - 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. If sourcemap locations have been specified with `s.addSourceMapLocation()`, they will be used here.
The returned sourcemap has two (non-enumerable) methods attached for convenience:
* `toString` - returns the equivalent of `JSON.stringify(map)`
* `toUrl` - returns a DataURI containing the sourcemap. Useful for doing this sort of thing:
```js
code += '\n//# sourceMappingURL=' + map.toUrl();
```
### 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.locate( index )
**DEPRECATED** since 0.10 see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
### s.locateOrigin( index )
**DEPRECATED** since 0.10 see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
### s.move( start, end, newIndex )
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`. 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.
### 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.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.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.isEmpty()
Returns true if the resulting source is empty (disregarding white space).
## Bundling
To concatenate several sources, use `MagicString.Bundle`:
```js
const bundle = new MagicString.Bundle();
bundle.addSource({
filename: 'foo.js',
content: new MagicString('var answer = 42;')
});
bundle.addSource({
filename: 'bar.js',
content: new MagicString('console.log( answer )')
});
// Advanced: a source can include an `indentExclusionRanges` property
// alongside `filename` and `content`. This will be passed to `s.indent()`
// - see documentation above
bundle.indent() // optionally, pass an indent string, otherwise it will be guessed
.prepend('(function () {\n')
.append('}());');
bundle.toString();
// (function () {
// var answer = 42;
// console.log( answer );
// }());
// options are as per `s.generateMap()` above
const map = bundle.generateMap({
file: 'bundle.js',
includeContent: true,
hires: true
});
```
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:
```js
const bundle = new MagicString.Bundle();
const source = new MagicString(someCode, {
filename: 'foo.js'
});
bundle.addSource(source);
```
## License
MIT

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View File

@@ -0,0 +1,221 @@
export interface BundleOptions {
intro?: string;
separator?: string;
}
export interface SourceMapOptions {
/**
* 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.
* If sourcemap locations have been specified with s.addSourceMapLocation(), they will be used here.
*/
hires?: boolean;
/**
* The filename where you plan to write the sourcemap.
*/
file?: string;
/**
* The filename of the file containing the original source.
*/
source?: string;
/**
* Whether to include the original content in the map's sourcesContent array.
*/
includeContent?: boolean;
}
export type SourceMapSegment =
| [number]
| [number, number, number, number]
| [number, number, number, number, number];
export interface DecodedSourceMap {
file: string;
sources: string[];
sourcesContent: string[];
names: string[];
mappings: SourceMapSegment[][];
}
export class SourceMap {
constructor(properties: DecodedSourceMap);
version: number;
file: string;
sources: string[];
sourcesContent: string[];
names: string[];
mappings: string;
/**
* Returns the equivalent of `JSON.stringify(map)`
*/
toString(): string;
/**
* Returns a DataURI containing the sourcemap. Useful for doing this sort of thing:
* `generateMap(options?: SourceMapOptions): SourceMap;`
*/
toUrl(): string;
}
export class Bundle {
constructor(options?: BundleOptions);
addSource(source: MagicString | { filename?: string, content: MagicString }): Bundle;
append(str: string, options?: BundleOptions): Bundle;
clone(): Bundle;
generateMap(options?: SourceMapOptions): SourceMap;
generateDecodedMap(options?: SourceMapOptions): DecodedSourceMap;
getIndentString(): string;
indent(indentStr?: string): Bundle;
indentExclusionRanges: ExclusionRange | Array<ExclusionRange>;
prepend(str: string): Bundle;
toString(): string;
trimLines(): Bundle;
trim(charType?: string): Bundle;
trimStart(charType?: string): Bundle;
trimEnd(charType?: string): Bundle;
isEmpty(): boolean;
length(): number;
}
export type ExclusionRange = [ number, number ];
export interface MagicStringOptions {
filename?: string,
indentExclusionRanges?: ExclusionRange | Array<ExclusionRange>;
}
export interface IndentOptions {
exclude?: ExclusionRange | Array<ExclusionRange>;
indentStart?: boolean;
}
export interface OverwriteOptions {
storeName?: boolean;
contentOnly?: boolean;
}
export default class MagicString {
constructor(str: string, options?: MagicStringOptions);
/**
* Adds the specified character index (with respect to the original string) to sourcemap mappings, if `hires` is false.
*/
addSourcemapLocation(char: number): void;
/**
* Appends the specified content to the end of the string.
*/
append(content: string): MagicString;
/**
* 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.
* See also `s.prependLeft(...)`.
*/
appendLeft(index: number, content: string): MagicString;
/**
* 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.
* See also `s.prependRight(...)`.
*/
appendRight(index: number, content: string): MagicString;
/**
* Does what you'd expect.
*/
clone(): MagicString;
/**
* Generates a version 3 sourcemap.
*/
generateMap(options?: SourceMapOptions): SourceMap;
/**
* Generates a sourcemap object with raw mappings in array form, rather than encoded as a string.
* Useful if you need to manipulate the sourcemap further, but most of the time you will use `generateMap` instead.
*/
generateDecodedMap(options?: SourceMapOptions): DecodedSourceMap;
getIndentString(): string;
/**
* 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.
*/
indent(options?: IndentOptions): MagicString;
/**
* 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.
*
* 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.
*/
indent(indentStr?: string, options?: IndentOptions): MagicString;
indentExclusionRanges: ExclusionRange | Array<ExclusionRange>;
/**
* Moves the characters from `start and `end` to `index`.
*/
move(start: number, end: number, index: number): MagicString;
/**
* Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply.
*
* 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.
*/
overwrite(start: number, end: number, content: string, options?: boolean | OverwriteOptions): MagicString;
/**
* Prepends the string with the specified content.
*/
prepend(content: string): MagicString;
/**
* Same as `s.appendLeft(...)`, except that the inserted content will go *before* any previous appends or prepends at index
*/
prependLeft(index: number, content: string): MagicString;
/**
* Same as `s.appendRight(...)`, except that the inserted content will go *before* any previous appends or prepends at `index`
*/
prependRight(index: number, content: string): MagicString;
/**
* 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.
*/
remove(start: number, end: number): MagicString;
/**
* 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.
*/
slice(start: number, end: number): string;
/**
* Returns a clone of `s`, with all content before the `start` and `end` characters of the original string removed.
*/
snip(start: number, end: number): MagicString;
/**
* Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start and end.
*/
trim(charType?: string): MagicString;
/**
* Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start.
*/
trimStart(charType?: string): MagicString;
/**
* Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the end.
*/
trimEnd(charType?: string): MagicString;
/**
* Removes empty lines from the start and end.
*/
trimLines(): MagicString;
lastChar(): string;
lastLine(): string;
/**
* Returns true if the resulting source is empty (disregarding white space).
*/
isEmpty(): boolean;
length(): number;
original: string;
/**
* Returns the generated string.
*/
toString(): string;
}

View File

@@ -0,0 +1,52 @@
{
"name": "magic-string",
"version": "0.25.9",
"description": "Modify strings, generate sourcemaps",
"keywords": [
"string",
"string manipulation",
"sourcemap",
"templating",
"transpilation"
],
"repository": "https://github.com/rich-harris/magic-string",
"license": "MIT",
"author": "Rich Harris",
"main": "dist/magic-string.cjs.js",
"module": "dist/magic-string.es.js",
"jsnext:main": "dist/magic-string.es.js",
"typings": "index.d.ts",
"files": [
"dist/*",
"index.d.ts",
"README.md"
],
"scripts": {
"build": "rollup -c",
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
"format": "prettier --single-quote --print-width 100 --use-tabs --write src/*.js src/**/*.js",
"lint": "eslint src test",
"prepare": "npm run build",
"prepublishOnly": "rm -rf dist && npm test",
"release": "bumpp -x \"npm run changelog\" --all --commit --tag --push && npm publish",
"pretest": "npm run lint && npm run build",
"test": "mocha",
"watch": "rollup -cw"
},
"dependencies": {
"sourcemap-codec": "^1.4.8"
},
"devDependencies": {
"@rollup/plugin-buble": "^0.21.3",
"@rollup/plugin-node-resolve": "^13.1.3",
"@rollup/plugin-replace": "^4.0.0",
"bumpp": "^7.1.1",
"conventional-changelog-cli": "^2.2.2",
"eslint": "^7.32.0",
"mocha": "^9.2.1",
"prettier": "^2.5.1",
"rollup": "^2.69.0",
"source-map": "^0.6.1",
"source-map-support": "^0.5.21"
}
}

View File

@@ -0,0 +1,41 @@
{
"name": "@vue/reactivity-transform",
"version": "3.2.47",
"description": "@vue/reactivity-transform",
"main": "dist/reactivity-transform.cjs.js",
"files": [
"dist"
],
"buildOptions": {
"formats": [
"cjs"
],
"prod": false
},
"types": "dist/reactivity-transform.d.ts",
"repository": {
"type": "git",
"url": "git+https://github.com/vuejs/core.git",
"directory": "packages/reactivity-transform"
},
"keywords": [
"vue"
],
"author": "Evan You",
"license": "MIT",
"bugs": {
"url": "https://github.com/vuejs/core/issues"
},
"homepage": "https://github.com/vuejs/core/tree/dev/packages/reactivity-transform#readme",
"dependencies": {
"@babel/parser": "^7.16.4",
"@vue/compiler-core": "3.2.47",
"@vue/shared": "3.2.47",
"estree-walker": "^2.0.2",
"magic-string": "^0.25.7"
},
"devDependencies": {
"@babel/core": "^7.16.0",
"@babel/types": "^7.16.0"
}
}