muggle-string 1.0.0-alpha.0 → 1.0.0-alpha.1

package/README.md

@@ -1,6 +1,6 @@
-Ranked, conflict-free rewrites of a source text, rendered as format-neutral segments.
+Ranked, conflict-free rewrites of a source text, rendered as format-neutral pieces.
 
-muggle-string has no dependencies and knows no mapping format: a rewrite renders text and source runs to a sink, and the consumer turns them into whatever its tooling maps with.
+muggle-string has no dependencies and knows no mapping format: a rewrite renders to pieces, new text and ranges of the source, and the consumer turns them into whatever its tooling maps with.
 
 > 1.0 replaces the segment-array helpers of 0.4 (`replace`, `replaceSourceRange`, `toString`, ...). They are gone, not deprecated.
 
@@ -9,7 +9,7 @@ muggle-string has no dependencies and knows no mapping format: a rewrite renders
 - Writers have ranks. A higher rank sits outside a lower one, and `core` sits outside all.
 - `insertBefore(offset, code)` and `insertAfter(offset, code)` attach code to a side of a char, so it goes wherever that char goes. `replace(start, end, code)` removes the text and puts `code` in the place of its first char.
 - Removals add up, so edits of different writers never conflict.
-- Only `core` moves text, with `cut(start, end, { data, placeholder })`. Cuts are nested or disjoint. A cut renders its text, with the edits of all writers in it, wherever its slice is placed, exactly once; the cut around it renders `placeholder` instead.
+- Text moves only by `cut(start, end, { data, placeholder })`, which every writer has. The cuts of all writers are nested or disjoint. A cut renders its text, with the edits of all writers in it, wherever its slice is placed, exactly once; the cut around it renders `placeholder` instead.
 - Code at the head or tail of a cut belongs to the outermost cut that has that edge.
 - `order` sorts the entries of one writer at one side of one char; equal keys keep call order.
 - The first render freezes the rewrite.
@@ -17,24 +17,33 @@ muggle-string has no dependencies and knows no mapping format: a rewrite renders
 ## Usage
 
 ```ts
-import { createSourceRewrite, type MappedSegment, type Segment } from 'muggle-string';
+import { createSourceRewrite } from 'muggle-string';
 
-const text = 'const props = defineProps<{ a: string }>();';
-const rewrite = createSourceRewrite<string, string>('setup', text);
+const text = 'log(name);\nconst name = "Ada";\n';
+const rewrite = createSourceRewrite<string, string>('main.js', text);
 const { core } = rewrite;
+const renamer = rewrite.writer(0);
 
-const body = core.cut(0, text.length, { data: 'body' });
-const typeArg = core.cut(text.indexOf('{'), text.lastIndexOf('}') + 1, { data: 'alias', placeholder: '__VLS_Props' });
-core.insertBefore(0, () => ['type __VLS_Props = ', typeArg, ';\n']);
-
-const segments: Segment<string, string>[] = [];
-body.render({
-	text: text => segments.push(text),
-	source: (rewrite, start, end, data) => segments.push([rewrite.text.slice(start, end), rewrite.source, start, data]),
-	segment: (segment: MappedSegment<string, string>) => segments.push(segment),
-});
-// type __VLS_Props = { a: string };
-// const props = defineProps<__VLS_Props>();
+for (const { index } of text.matchAll(/\bname\b/g)) {
+	renamer.replace(index, index + 'name'.length, 'user');
+}
+
+const file = core.cut(0, text.length, { data: 'file' });
+const declaration = core.cut(text.indexOf('const'), text.length, { data: 'declaration' });
+core.insertBefore(0, declaration);
+
+const pieces = file.pieces();
+// [{ source: 'main.js', start: 11, end: 17, data: 'declaration' }, 'user', ..., { source: 'main.js', start: 0, end: 4, data: 'file' }, ...]
+// const user = "Ada";
+// log(user);
 ```
 
-Code is a string, or a function, called at most once and only if the code renders, that yields strings, mapped segments, and slices.
+## Pieces
+
+```ts
+type Piece<Source, Data> = string | { source: Source; start: number; end: number; data: Data; text?: string };
+```
+
+A string is new text, which maps nowhere. An object is the range `start`..`end` of the text of `source`: without `text` it copies the text there, and with `text` it is code that stands for the range, mapped as the consumer of the pieces decides. The kept text of a rewrite renders as pieces without `text`, with the data of the cut that owns them.
+
+Code is a piece, a slice, which renders its cut in place, or an array of code. `slice.pieces(out)` appends to `out` and returns it.

package/out/sourceRewrite.d.ts

@@ -1,18 +1,15 @@
-import type { MappedSegment, Segment } from './types';
-/** Generated code: eager text, or a function that is called at most once, and only if the code renders. */
-export type RewriteCode<Source, Data> = string | (() => Iterable<Segment<Source, Data> | RewriteSlice<Source, Data>>);
+import type { Piece } from './types';
+/** Generated code: text, pieces, and slices, which render their cut in place. */
+export type RewriteCode<Source, Data> = Piece<Source, Data> | RewriteSlice<Source, Data> | readonly RewriteCode<Source, Data>[];
 export interface InsertOptions {
     /** Ascending among the entries of one writer at one side of one char; equal keys keep call order. Default 0. */
     order?: number;
 }
-/** Where a slice renders to. */
-export interface RewriteSink<Source, Data> {
-    /** Generated text, never empty. */
-    text(text: string): void;
-    /** The kept chars `start`..`end` (never empty) of the text of `rewrite`, owned by a cut whose data is `data`. */
-    source(rewrite: SourceRewrite<Source, Data>, start: number, end: number, data: Data): void;
-    /** A mapped segment that generated code carries. */
-    segment(segment: MappedSegment<Source, Data>): void;
+export interface CutOptions<Source, Data> {
+    /** The data of the kept pieces of the cut. */
+    data: Data;
+    /** The code that takes the place of the cut in the cut that contains it. */
+    placeholder?: RewriteCode<Source, Data>;
 }
 export interface RewriteWriter<Source, Data> {
     /**
@@ -27,30 +24,26 @@ export interface RewriteWriter<Source, Data> {
     insertAfter(offset: number, code: RewriteCode<Source, Data>, options?: InsertOptions): void;
     /** The text at `start`..`end` (not empty) is not rendered; `code` takes the place of its first char. */
     replace(start: number, end: number, code: RewriteCode<Source, Data>, options?: InsertOptions): void;
-}
-export interface CoreRewriteWriter<Source, Data> extends RewriteWriter<Source, Data> {
     /**
      * The text at `start`..`end`, with the edits of all writers in it, rendered where the returned slice is placed,
-     * exactly once. In the cut that contains it, `placeholder` takes its place. Cuts are nested or disjoint, and of two
-     * cuts of one range the later is inside the earlier. A zero-width cut owns no char and has no placeholder; on an
-     * empty text, the first one renders the inserts.
+     * exactly once. In the cut that contains it, `placeholder` takes its place. The cuts of all writers are nested or
+     * disjoint, and of two cuts of one range the later is inside the earlier. A zero-width cut owns no char and has no
+     * placeholder; on an empty text, the first one renders the inserts.
      */
-    cut(start: number, end: number, options: {
-        data: Data;
-        placeholder?: RewriteCode<Source, Data>;
-    }): RewriteSlice<Source, Data>;
+    cut(start: number, end: number, options: CutOptions<Source, Data>): RewriteSlice<Source, Data>;
 }
 export interface RewriteSlice<Source, Data> {
-    render(sink: RewriteSink<Source, Data>): void;
+    /** Appends the pieces of the slice to `out`, and returns `out`. A kept piece has no `text`. */
+    pieces(out?: Piece<Source, Data>[]): Piece<Source, Data>[];
 }
 /**
- * Edits of one source text by ranked writers. Inserts attach to a side of a char, removals add up, and only core
- * moves text, by nested cuts, so edits never conflict. The first render freezes the edits.
+ * Edits of one source text by ranked writers. Inserts attach to a side of a char, removals add up, and text moves
+ * only by nested cuts, so edits never conflict. The first render freezes the edits.
  */
 export interface SourceRewrite<Source, Data> {
     readonly source: Source;
     readonly text: string;
-    readonly core: CoreRewriteWriter<Source, Data>;
+    readonly core: RewriteWriter<Source, Data>;
     /** The writer of `rank`, a non-negative integer. A higher rank sits outside a lower one, and core outside all. */
     writer(rank: number): RewriteWriter<Source, Data>;
 }

package/out/sourceRewrite.js

@@ -51,13 +51,15 @@ class Edits {
             this.side[i] = record.side;
             this.code[i] = record.code;
         }
+        this.records = [];
     }
     /** The first index from `low` whose anchor is at or after `offset`. */
     lowerBound(offset, low) {
-        let high = this.at.length;
+        const at = this.at;
+        let high = at.length;
         while (low < high) {
             const mid = (low + high) >>> 1;
-            if (this.at[mid] < offset) {
+            if (at[mid] < offset) {
                 low = mid + 1;
             }
             else {
@@ -76,29 +78,14 @@ class Rewrite {
         this.head = new Edits();
         /** `insertBefore(length)`: after all text. */
         this.tail = new Edits();
-        /** Removed ranges as flat start, end pairs; merged when frozen. */
-        this.removals = [];
+        /** Removed ranges as flat start, end pairs. */
+        this.removalPairs = [];
+        /** The removed ranges, sorted and merged, filled when frozen. */
+        this.removals = new Int32Array(0);
         /** The top-level cuts, sorted and disjoint. */
         this.roots = [];
         this.frozen = false;
-        const core = this.createWriter(coreRank);
-        core.cut = (start, end, { data, placeholder }) => {
-            this.check(start, end);
-            const cut = new Cut(this, start, end, data, placeholder);
-            if (start === end) {
-                if (placeholder !== undefined) {
-                    throw new RangeError(`The empty cut ${start}..${end} cannot have a placeholder.`);
-                }
-                if (!this.text.length) {
-                    this.firstEmpty ??= cut;
-                }
-            }
-            else {
-                this.insertCut(cut);
-            }
-            return cut;
-        };
-        this.core = core;
+        this.core = this.createWriter(coreRank);
     }
     writer(rank) {
         if (!Number.isInteger(rank) || rank < 0 || rank >= coreRank) {
@@ -134,7 +121,23 @@ class Rewrite {
                     throw new RangeError(`The replace at ${start}..${end} removes no char.`);
                 }
                 this.edits.push(start, 1 /* Side.Slot */, rank, getOrder(options), code);
-                this.removals.push(start, end);
+                this.removalPairs.push(start, end);
+            },
+            cut: (start, end, { data, placeholder }) => {
+                this.check(start, end);
+                const cut = new Cut(this, start, end, data, placeholder);
+                if (start === end) {
+                    if (placeholder !== undefined) {
+                        throw new RangeError(`The empty cut ${start}..${end} cannot have a placeholder.`);
+                    }
+                    if (!this.text.length) {
+                        this.firstEmpty ??= cut;
+                    }
+                }
+                else {
+                    this.insertCut(cut);
+                }
+                return cut;
             },
         };
     }
@@ -201,7 +204,7 @@ class Rewrite {
         this.edits.freeze();
         this.head.freeze();
         this.tail.freeze();
-        const removals = this.removals;
+        const removals = this.removalPairs;
         const pairs = removals.length >> 1;
         for (let pair = 1; pair < pairs; pair++) {
             if (removals[2 * pair - 2] > removals[2 * pair]) {
@@ -229,6 +232,8 @@ class Rewrite {
             }
         }
         removals.length = merged;
+        this.removals = Int32Array.from(removals);
+        this.removalPairs = [];
         for (const root of this.roots) {
             root.isRoot = true;
         }
@@ -253,59 +258,26 @@ class Cut {
         this.isRoot = false;
         this.placed = false;
     }
-    render(sink) {
+    pieces(out = []) {
         if (this.placed) {
             throw new Error(`The cut ${this.start}..${this.end} is placed twice.`);
         }
         this.placed = true;
         const rewrite = this.rewrite;
         rewrite.freeze();
-        const { edits, removals, head, tail } = rewrite;
-        const { start, end, children, data } = this;
+        const { edits, head, tail } = rewrite;
+        const { start, end, children } = this;
         if (start === end) {
             if (this === rewrite.firstEmpty) {
-                renderAll(head, sink);
-                renderAll(tail, sink);
+                pushAll(head, out);
+                pushAll(tail, out);
             }
-            return;
+            return out;
         }
         if (this.isRoot && start === 0) {
-            renderAll(head, sink);
+            pushAll(head, out);
         }
-        const removalsEnd = removals.length;
-        let pos = start;
-        let removal = 0;
-        // the first removal that ends after `pos`, from `removal` on
-        const seekRemoval = () => {
-            let low = removal >> 1;
-            let high = removalsEnd >> 1;
-            while (low < high) {
-                const mid = (low + high) >>> 1;
-                if (removals[2 * mid + 1] <= pos) {
-                    low = mid + 1;
-                }
-                else {
-                    high = mid;
-                }
-            }
-            removal = low * 2;
-        };
-        // the kept chars from `pos` to `to`, as runs between the removals
-        const renderText = (to) => {
-            while (pos < to) {
-                while (removal < removalsEnd && removals[removal + 1] <= pos) {
-                    removal += 2;
-                }
-                if (removal < removalsEnd && removals[removal] <= pos) {
-                    pos = Math.min(removals[removal + 1], to);
-                    continue;
-                }
-                const stop = removal < removalsEnd ? Math.min(removals[removal], to) : to;
-                sink.source(rewrite, pos, stop, data);
-                pos = stop;
-            }
-        };
-        seekRemoval();
+        const walker = new Walker(rewrite.removals, rewrite.source, this.data, out, start);
         const { at, side, code } = edits;
         const size = at.length;
         let edit = edits.lowerBound(start, 0);
@@ -313,50 +285,103 @@ class Cut {
             const child = children[index];
             const until = child ? child.start : end;
             for (; edit < size && at[edit] < until; edit++) {
-                renderText(side[edit] === 2 /* Side.After */ ? at[edit] + 1 : at[edit]);
-                renderCode(code[edit], sink);
+                walker.keep(side[edit] === 2 /* Side.After */ ? at[edit] + 1 : at[edit]);
+                pushCode(code[edit], out);
             }
             if (!child) {
                 break;
             }
-            renderText(child.start);
+            walker.keep(child.start);
             if (child.placeholder !== undefined) {
-                renderCode(child.placeholder, sink);
+                pushCode(child.placeholder, out);
             }
-            pos = child.end;
-            seekRemoval();
+            walker.skip(child.end);
             edit = edits.lowerBound(child.end, edit);
         }
-        renderText(end);
+        walker.keep(end);
         if (this.isRoot && end === rewrite.text.length) {
-            renderAll(tail, sink);
+            pushAll(tail, out);
         }
+        return out;
     }
 }
-function renderAll(edits, sink) {
+/** Pushes the kept chars of one cut, as pieces between the removals. */
+class Walker {
+    constructor(removals, source, data, out, pos) {
+        this.removals = removals;
+        this.source = source;
+        this.data = data;
+        this.out = out;
+        this.pos = pos;
+        /** The first removal that ends after `pos`. */
+        this.removal = 0;
+        this.seek();
+    }
+    /** The kept chars from `pos` to `to`. */
+    keep(to) {
+        const { removals, out } = this;
+        const size = removals.length;
+        let { pos, removal } = this;
+        while (pos < to) {
+            while (removal < size && removals[removal + 1] <= pos) {
+                removal += 2;
+            }
+            if (removal < size && removals[removal] <= pos) {
+                pos = removals[removal + 1] < to ? removals[removal + 1] : to;
+                continue;
+            }
+            const stop = removal < size && removals[removal] < to ? removals[removal] : to;
+            out.push({ source: this.source, start: pos, end: stop, data: this.data });
+            pos = stop;
+        }
+        this.pos = pos;
+        this.removal = removal;
+    }
+    /** Moves past the chars up to `to`, which a child cut owns. */
+    skip(to) {
+        this.pos = to;
+        this.seek();
+    }
+    seek() {
+        const removals = this.removals;
+        let low = this.removal >> 1;
+        let high = removals.length >> 1;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            if (removals[2 * mid + 1] <= this.pos) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        this.removal = low * 2;
+    }
+}
+function pushAll(edits, out) {
     for (const code of edits.code) {
-        renderCode(code, sink);
+        pushCode(code, out);
     }
 }
-function renderCode(code, sink) {
+function pushCode(code, out) {
     if (typeof code === 'string') {
         if (code) {
-            sink.text(code);
+            out.push(code);
         }
-        return;
     }
-    for (const item of code()) {
-        if (typeof item === 'string') {
-            if (item) {
-                sink.text(item);
-            }
-        }
-        else if (Array.isArray(item)) {
-            sink.segment(item);
-        }
-        else {
-            item.render(sink);
+    else if (code instanceof Cut) {
+        code.pieces(out);
+    }
+    else if (isCodeArray(code)) {
+        for (let index = 0; index < code.length; index++) {
+            pushCode(code[index], out);
         }
     }
+    else {
+        out.push(code);
+    }
+}
+function isCodeArray(code) {
+    return Array.isArray(code);
 }
 //# sourceMappingURL=sourceRewrite.js.map

package/out/types.d.ts

@@ -1,4 +1,12 @@
-/** Generated code: plain text, or text that maps to `sourceOffset` of `source`. */
-export type Segment<Source, Data> = string | [text: string, source: Source, sourceOffset: number, data: Data];
-/** A segment of generated code that maps to a source. */
-export type MappedSegment<Source, Data> = Exclude<Segment<Source, Data>, string>;
+/**
+ * Generated code: new text, which maps nowhere, or the range `start`..`end` of the text of `source`. A range without
+ * `text` is a copy of the text there; `text` is code that stands for the range, mapped as its consumer decides. An
+ * empty range is an anchor.
+ */
+export type Piece<Source, Data> = string | {
+    source: Source;
+    start: number;
+    end: number;
+    data: Data;
+    text?: string;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "muggle-string",
-	"version": "1.0.0-alpha.0",
-	"description": "Ranked, conflict-free rewrites of a source text, rendered as format-neutral segments",
+	"version": "1.0.0-alpha.1",
+	"description": "Ranked, conflict-free rewrites of a source text, rendered as format-neutral pieces",
 	"main": "out/index.js",
 	"types": "out/index.d.ts",
 	"license": "MIT",