rolldown-string 0.0.0 → 0.2.0

package/README.md

@@ -4,7 +4,12 @@
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![Unit Test][unit-test-src]][unit-test-href]
 
-undefined
+A compatibility layer for [magic-string](https://github.com/Rich-Harris/magic-string) to work with Rolldown and other bundlers.
+
+- In Rolldown, [native `magic-string`](https://rolldown.rs/in-depth/native-magic-string) is used to optimize performance.
+- If native support is unavailable, it gracefully falls back to the JavaScript implementation of `magic-string`.
+
+Recommended for use with [unplugin](https://github.com/unjs/unplugin).
 
 ## Install
 
@@ -12,6 +17,42 @@ undefined
 npm i rolldown-string
 ```
 
+## Usage
+
+### `withMagicString`
+
+Higher-order function to create a `transform` hook with `magic-string` support.
+
+```ts
+import { withMagicString } from 'rolldown-string'
+
+const plugin = {
+  transform: withMagicString((s, id) => {
+    // your transformations...
+    s.replace('42', '43')
+  }),
+}
+```
+
+### `rolldownString` / `generateTransform`
+
+More flexible way to use `rolldown-string`.
+
+```ts
+import { generateTransform, rolldownString } from 'rolldown-string'
+
+const yourPlugin = {
+  transform(code, id, meta) {
+    const s = rolldownString(code, id, meta)
+
+    // your transformations...
+    s.replace('42', '43')
+
+    return generateTransform(s, id)
+  },
+}
+```
+
 ## Sponsors
 
 <p align="center">

package/dist/index.d.ts

@@ -5,6 +5,10 @@ import { BindingMagicString } from "rolldown";
 type ObjectIntersection<A, B> = { [K in keyof A & keyof B]: A[K] };
 type RolldownString = ObjectIntersection<MagicString, BindingMagicString>;
 declare function rolldownString(code: string, id: string, meta?: any): RolldownString;
+type Awaitable<T> = T | Promise<T>;
+type HandlerReturn = string | MagicString | BindingMagicString | RolldownString | void | undefined;
+type Handler<Meta> = (s: RolldownString, id: string, meta: Meta) => Awaitable<HandlerReturn>;
+declare function withMagicString<Meta>(handler: Handler<Meta>): (code: string, id: string, meta: Meta) => Awaitable<CodeTransform | undefined>;
 /**
 * The result of code transformation.
 */
@@ -15,6 +19,6 @@ interface CodeTransform {
 /**
 * Generate an object of code and source map from MagicString.
 */
-declare function generateTransform(s: MagicString | BindingMagicString | RolldownString | undefined, id: string): CodeTransform | undefined;
+declare function generateTransform(s: MagicString | BindingMagicString | RolldownString | undefined, id: string, force?: boolean): CodeTransform | undefined;
 //#endregion
-export { CodeTransform, RolldownString, generateTransform, rolldownString };
+export { CodeTransform, Handler, HandlerReturn, RolldownString, generateTransform, rolldownString, withMagicString };

package/dist/index.js

@@ -4,12 +4,24 @@ import MagicString from "magic-string";
 function rolldownString(code, id, meta) {
 	return meta?.magicString || new MagicString(code, { filename: id });
 }
+function withMagicString(handler) {
+	return (code, id, meta) => {
+		const s = rolldownString(code, id, meta);
+		const res = handler(s, id, meta);
+		const callback = (res$1) => {
+			if (typeof res$1 === "string") return { code: res$1 };
+			return generateTransform(res$1 || s, id, !!res$1);
+		};
+		if (res instanceof Promise) return res.then(callback);
+		return callback(res);
+	};
+}
 /**
 * Generate an object of code and source map from MagicString.
 */
-function generateTransform(s, id) {
+function generateTransform(s, id, force) {
 	if (s?.constructor.name === "BindingMagicString") return { code: s };
-	if (s?.hasChanged()) return {
+	if (s && (force || s.hasChanged())) return {
 		code: s.toString(),
 		get map() {
 			return s.generateMap({
@@ -22,4 +34,4 @@ function generateTransform(s, id) {
 }
 
 //#endregion
-export { generateTransform, rolldownString };
+export { generateTransform, rolldownString, withMagicString };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "rolldown-string",
   "type": "module",
-  "version": "0.0.0",
-  "description": "undefined",
+  "version": "0.2.0",
+  "description": "A compatibility layer for magic-string to work with Rolldown and other bundlers.",
   "author": "Kevin Deng <sxzz@sxzz.moe>",
   "license": "MIT",
   "funding": "https://github.com/sponsors/sxzz",
@@ -14,6 +14,12 @@
   "bugs": {
     "url": "https://github.com/sxzz/rolldown-string/issues"
   },
+  "keywords": [
+    "rolldown",
+    "unplugin",
+    "magic-string",
+    "rollup"
+  ],
   "exports": {
     ".": "./dist/index.js",
     "./package.json": "./package.json"
@@ -36,6 +42,7 @@
   "devDependencies": {
     "@sxzz/eslint-config": "^7.4.3",
     "@sxzz/prettier-config": "^2.2.6",
+    "@sxzz/test-utils": "^0.5.14",
     "@types/node": "^24.10.4",
     "@typescript/native-preview": "7.0.0-dev.20251214.1",
     "bumpp": "^10.3.2",