mrkr 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xvezda <xvezda@naver.com>
+
+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.

package/README.md

@@ -0,0 +1,111 @@
+# mrkr
+
+`mrkr` is a lightweight TypeScript library providing a `markable` template tag. It allows you to create strings with embedded markers to easily track positions, compose strings, and split them at marked locations.
+
+## Features
+
+- Create strings with markers using a simple template literal syntax.
+- Automatically tracks the `start` and `end` positions of markers.
+- Compose `markable` strings together, preserving marker information.
+- Use `markRef` to create references to specific markers and find their offsets.
+- Split strings into parts using the `cut()` method.
+- Fully typed with TypeScript.
+
+## Installation
+
+Install the dependencies:
+
+```bash
+pnpm install
+```
+
+## Usage
+
+### Basic Marking
+
+Import `markable` and `mark` to create your first marked string. The `mark` symbol indicates where a marker should be placed.
+
+```typescript
+import { markable, mark as v } from 'mrkr';
+
+const str = markable`Hello, ${v}world!`;
+
+console.log(str.toString()); // "Hello, world!"
+
+// Get the position of the first and last marks
+console.log(str.start);      // 7
+console.log(str.end);        // 7
+```
+
+### Multiple Markers and `cut()`
+
+You can place multiple marks. The `cut()` method will split the string at each marker.
+
+```typescript
+import { markable, mark as v } from 'mrkr';
+
+const str = markable`foo${v}bar${v}baz`;
+
+console.log(str.cut()); // ['foo', 'bar', 'baz']
+console.log(str.start); // 3
+console.log(str.end);   // 6
+```
+
+### Composition
+
+`markable` strings can be nested and composed seamlessly.
+
+```typescript
+import { markable, mark as v } from 'mrkr';
+
+const foo = markable`fo${v}o`;
+const bar = markable`b${v}ar`;
+const foobar = markable`${foo}${v}${bar}`;
+
+console.log(foobar.toString()); // "foobar"
+console.log(foobar.start);      // 2 (from foo)
+console.log(foobar.end);        // 4 (from bar)
+
+// .cut() splits at all nested and new marks
+console.log(foobar.cut());      // ['fo', 'o', 'b', 'ar']
+```
+
+### `markRef` for Tagged Markers
+
+For more advanced control, `markRef` allows you to create a reference to a marker. This reference can be used to find the offset of that specific marker, even in composed strings.
+
+```typescript
+import { markable, markRef } from 'mrkr';
+
+const nameRef = markRef();
+const greeting = markable`Hello, ${nameRef}John Doe!`;
+
+// Find the position of the marker using the reference
+const namePosition = nameRef.offsetFrom(greeting);
+// You can also get it from the string instance
+// const namePosition = greeting.offsetOf(nameRef);
+
+console.log(namePosition); // 7
+console.log(greeting.substring(greeting.start)); // "John Doe!"
+
+// The reference works across compositions
+const announcement = markable`Attention! ${greeting}. Welcome.`;
+const namePositionInAnnouncement = nameRef.offsetFrom(announcement);
+
+console.log(namePositionInAnnouncement); // 18
+```
+
+## Development
+
+Build the library:
+
+```bash
+pnpm run build
+```
+
+Build the library in watch mode:
+
+```bash
+pnpm run dev
+```
+

package/dist/index.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    mark: ()=>mark,
+    markRef: ()=>markRef,
+    markable: ()=>markable
+});
+const mark = Symbol('mark');
+class MarkRef {
+    references = new Set();
+    addReference(markable) {
+        this.references.add(markable);
+    }
+    offsetFrom(markable, from = 0) {
+        return markable.offsetOf(this, from);
+    }
+    lastOffsetFrom(markable, from) {
+        return markable.lastOffsetOf(this, from);
+    }
+}
+function markRef() {
+    return new MarkRef();
+}
+class Markable extends String {
+    start = -1;
+    end = -1;
+    marks = [];
+    constructor(value){
+        super(value);
+    }
+    cut() {
+        if (0 === this.marks.length) return [
+            this.toString()
+        ];
+        const parts = [];
+        let lastIndex = 0;
+        const addPart = (part)=>{
+            if (part) parts.push(part);
+        };
+        for (const mark of this.marks){
+            addPart(this.toString().slice(lastIndex, mark.offset));
+            lastIndex = mark.offset;
+        }
+        addPart(this.toString().slice(lastIndex));
+        return parts;
+    }
+    offsetOf(ref, from = 0) {
+        for (const mark of this.marks)if (mark.ref === ref && mark.offset >= from) return mark.offset;
+        return -1;
+    }
+    lastOffsetOf(ref, from) {
+        let lastOffset = -1;
+        for (const mark of this.marks)if (mark.ref === ref && (void 0 === from || mark.offset <= from)) lastOffset = mark.offset;
+        return lastOffset;
+    }
+}
+class MarkableBuilder {
+    start = -1;
+    end = -1;
+    marks = [];
+    withStart(position) {
+        this.start = position;
+        return this;
+    }
+    withEnd(position) {
+        this.end = position;
+        return this;
+    }
+    withMarks(marks) {
+        this.marks = marks;
+        return this;
+    }
+    build(value) {
+        const markable = new Markable(value);
+        markable.start = this.start;
+        markable.end = this.end;
+        markable.marks = this.marks;
+        return markable;
+    }
+}
+const markable = (strings, ...values)=>{
+    let string = '';
+    let start = -1;
+    let end = -1;
+    const marks = [];
+    const refs = [];
+    for(let i = 0; i < strings.length; i++){
+        string += strings[i];
+        if (i < values.length) if (values[i] === mark || values[i] instanceof MarkRef) {
+            if (-1 === start) start = string.length;
+            end = string.length;
+            if (values[i] instanceof MarkRef) {
+                refs.push(values[i]);
+                marks.push({
+                    offset: string.length,
+                    ref: values[i]
+                });
+            } else marks.push({
+                offset: string.length
+            });
+        } else if (values[i] instanceof Markable) {
+            const markableValue = values[i];
+            const offset = string.length;
+            string += markableValue.toString();
+            for (const m of markableValue.marks){
+                const markInfo = {
+                    offset: m.offset + offset
+                };
+                if (m.ref) {
+                    markInfo.ref = m.ref;
+                    refs.push(m.ref);
+                }
+                marks.push(markInfo);
+            }
+            if (-1 !== markableValue.start) {
+                const absoluteStart = markableValue.start + offset;
+                if (-1 === start || absoluteStart < start) start = absoluteStart;
+            }
+            if (-1 !== markableValue.end) {
+                const absoluteEnd = markableValue.end + offset;
+                if (absoluteEnd > end) end = absoluteEnd;
+            }
+        } else string += String(values[i]);
+    }
+    const result = new MarkableBuilder().withStart(start).withEnd(end).withMarks(marks).build(string);
+    for (const ref of refs)ref.addReference(result);
+    return result;
+};
+exports.mark = __webpack_exports__.mark;
+exports.markRef = __webpack_exports__.markRef;
+exports.markable = __webpack_exports__.markable;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "mark",
+    "markRef",
+    "markable"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export declare const mark: unique symbol;
+export type Mark = typeof mark;
+export type MarkInfo = {
+    offset: number;
+    ref?: MarkRef;
+};
+declare class MarkRef {
+    references: Set<Markable>;
+    addReference(markable: Markable): void;
+    offsetFrom(markable: Markable, from?: number): number;
+    lastOffsetFrom(markable: Markable, from?: number): number;
+}
+export declare function markRef(): MarkRef;
+declare class Markable extends String {
+    start: number;
+    end: number;
+    marks: readonly MarkInfo[];
+    constructor(value: string);
+    cut(): string[];
+    offsetOf(ref: MarkRef, from?: number): number;
+    lastOffsetOf(ref: MarkRef, from?: number): number;
+}
+export declare const markable: (strings: TemplateStringsArray, ...values: any[]) => Markable;
+export {};

package/dist/index.js

@@ -0,0 +1,122 @@
+const src_mark = Symbol('mark');
+class MarkRef {
+    references = new Set();
+    addReference(markable) {
+        this.references.add(markable);
+    }
+    offsetFrom(markable, from = 0) {
+        return markable.offsetOf(this, from);
+    }
+    lastOffsetFrom(markable, from) {
+        return markable.lastOffsetOf(this, from);
+    }
+}
+function markRef() {
+    return new MarkRef();
+}
+class Markable extends String {
+    start = -1;
+    end = -1;
+    marks = [];
+    constructor(value){
+        super(value);
+    }
+    cut() {
+        if (0 === this.marks.length) return [
+            this.toString()
+        ];
+        const parts = [];
+        let lastIndex = 0;
+        const addPart = (part)=>{
+            if (part) parts.push(part);
+        };
+        for (const mark of this.marks){
+            addPart(this.toString().slice(lastIndex, mark.offset));
+            lastIndex = mark.offset;
+        }
+        addPart(this.toString().slice(lastIndex));
+        return parts;
+    }
+    offsetOf(ref, from = 0) {
+        for (const mark of this.marks)if (mark.ref === ref && mark.offset >= from) return mark.offset;
+        return -1;
+    }
+    lastOffsetOf(ref, from) {
+        let lastOffset = -1;
+        for (const mark of this.marks)if (mark.ref === ref && (void 0 === from || mark.offset <= from)) lastOffset = mark.offset;
+        return lastOffset;
+    }
+}
+class MarkableBuilder {
+    start = -1;
+    end = -1;
+    marks = [];
+    withStart(position) {
+        this.start = position;
+        return this;
+    }
+    withEnd(position) {
+        this.end = position;
+        return this;
+    }
+    withMarks(marks) {
+        this.marks = marks;
+        return this;
+    }
+    build(value) {
+        const markable = new Markable(value);
+        markable.start = this.start;
+        markable.end = this.end;
+        markable.marks = this.marks;
+        return markable;
+    }
+}
+const src_markable = (strings, ...values)=>{
+    let string = '';
+    let start = -1;
+    let end = -1;
+    const marks = [];
+    const refs = [];
+    for(let i = 0; i < strings.length; i++){
+        string += strings[i];
+        if (i < values.length) if (values[i] === src_mark || values[i] instanceof MarkRef) {
+            if (-1 === start) start = string.length;
+            end = string.length;
+            if (values[i] instanceof MarkRef) {
+                refs.push(values[i]);
+                marks.push({
+                    offset: string.length,
+                    ref: values[i]
+                });
+            } else marks.push({
+                offset: string.length
+            });
+        } else if (values[i] instanceof Markable) {
+            const markableValue = values[i];
+            const offset = string.length;
+            string += markableValue.toString();
+            for (const m of markableValue.marks){
+                const markInfo = {
+                    offset: m.offset + offset
+                };
+                if (m.ref) {
+                    markInfo.ref = m.ref;
+                    refs.push(m.ref);
+                }
+                marks.push(markInfo);
+            }
+            if (-1 !== markableValue.start) {
+                const absoluteStart = markableValue.start + offset;
+                if (-1 === start || absoluteStart < start) start = absoluteStart;
+            }
+            if (-1 !== markableValue.end) {
+                const absoluteEnd = markableValue.end + offset;
+                if (absoluteEnd > end) end = absoluteEnd;
+            }
+        } else string += String(values[i]);
+    }
+    const result = new MarkableBuilder().withStart(start).withEnd(end).withMarks(marks).build(string);
+    for (const ref of refs)ref.addReference(result);
+    return result;
+};
+export { markRef, src_mark as mark, src_markable as markable };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "mrkr",
+  "version": "0.0.0",
+  "type": "module",
+  "author": "Xvezda <xvezda@naver.com>",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@rslib/core": "^0.19.3",
+    "@rstest/core": "^0.8.0",
+    "@types/node": "^24.10.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "rstest"
+  }
+}