@nebulaaa/linked-list 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @linked-list
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+高性能泛型链表实现，包含单向链表 (`LinkedList`) 和双向链表 (`DoublyLinkedList`)。
+
+## 特性
+- **泛型支持**：支持任意类型 `T`。
+- **遍历安全**：`Each` 遍历在回调中执行 `Push` 或 `Remove` 时表现稳定，不会导致死循环或指针丢失。
+- **双向校验**：双向链表提供可选的归属校验机制，确保操作的节点确实属于当前链表。
+- **内存友好**：出链节点指针会被显式清空，优化 GC 效率。
+
+---
+
+## 1. LinkedList (单向链表)
+
+基础的单向链表，适用于简单的队列或栈场景。
+
+### 公共接口
+| 方法 | 描述 | 时间复杂度 |
+| :--- | :--- | :--- |
+| `Push(value: T): this` | 在链表尾部追加节点 | $O(1)$ |
+| `Unshift(value: T): this` | 在链表头部插入节点 | $O(1)$ |
+| `Shift(): T \| undefined` | 移除并返回头节点的值 | $O(1)$ |
+| `Pop(): T \| undefined` | 移除并返回尾节点的值 | $O(n)$ |
+| `Find(predicate): Node \| null` | 根据条件查找第一个匹配节点 | $O(n)$ |
+| `Remove(predicate): boolean` | 删除第一个匹配条件的节点 | $O(n)$ |
+| `Each(callback): void` | 遍历所有节点 | $O(n)$ |
+| `ToArray(): T[]` | 将链表转换为普通数组 | $O(n)$ |
+| `Size: number` | 获取当前链表长度 (Getter) | $O(1)$ |
+| `IsEmpty: boolean` | 判断链表是否为空 (Getter) | $O(1)$ |
+
+---
+
+## 2. DoublyLinkedList (双向链表)
+
+支持双向遍历和高效尾部操作的链表，适用于需要频繁在两端或中间插入/删除的场景。
+
+### 公共接口
+| 方法 | 描述 | 时间复杂度 |
+| :--- | :--- | :--- |
+| `Push(value: T): this` | 在尾部追加节点 | $O(1)$ |
+| `Unshift(value: T): this` | 在头部插入节点 | $O(1)$ |
+| `Pop(): T \| undefined` | 移除并返回尾部节点的值 | $O(1)$ |
+| `Shift(): T \| undefined` | 移除并返回头部节点的值 | $O(1)$ |
+| `InsertAfter(node, value): Node \| null` | 在指定节点后插入 | $O(1)$ / $O(n)^*$ |
+| `InsertBefore(node, value): Node \| null` | 在指定节点前插入 | $O(1)$ / $O(n)^*$ |
+| `Remove(node): boolean` | 删除指定节点 | $O(1)$ / $O(n)^*$ |
+| `Find(predicate): Node \| null` | 根据条件查找第一个匹配节点 | $O(n)$ |
+| `Each(callback): void` | 遍历所有节点 | $O(n)$ |
+| `ToArray(): T[]` | 将链表转换为普通数组 | $O(n)$ |
+| `First: Node \| null` | 获取头节点 (Getter) | $O(1)$ |
+| `Last: Node \| null` | 获取尾节点 (Getter) | $O(1)$ |
+| `Size: number` | 获取当前链表长度 (Getter) | $O(1)$ |
+| `IsEmpty: boolean` | 判断链表是否为空 (Getter) | $O(1)$ |
+
+### 归属校验 (`CheckOwnership`)
+双向链表引入了 `CheckOwnership` 标志位，用于控制是否在 `Remove` 和 `Insert` 操作时校验节点归属：
+- **`CheckOwnership = false` (默认)**: 追求极致性能，直接操作指针。复杂度 $O(1)$。
+- **`CheckOwnership = true`**: 增加安全性，防止误操作非本链表节点导致结构损坏。复杂度升至 $O(n)$。
+
+---
+
+## 示例
+
+```typescript
+import { LinkedList, DoublyLinkedList } from '@linked-list';
+
+// 单向链表
+const list = new LinkedList<number>();
+list.Push(1).Push(2).Unshift(0); // [0, 1, 2]
+list.Each((v, i) => console.log(i, v));
+
+// 双向链表
+const dlist = new DoublyLinkedList<string>();
+dlist.Push('A').Push('B');
+dlist.CheckOwnership = true; // 开启安全检查
+const node = dlist.First;
+dlist.InsertAfter(node!, 'Mid'); // [A, Mid, B]
+```

package/dist/linked-list.cjs

@@ -0,0 +1,408 @@
+'use strict';
+
+/**
+ * 泛型单向链表节点
+ */
+class LinkedListNode {
+    constructor(value) {
+        /** 指向下一个节点，末尾为 null */
+        this.Next = null;
+        this.Value = value;
+    }
+}
+/**
+ * 泛型链表
+ *
+ * 主要方法：
+ * - Push(value)      : 在链表尾部追加节点
+ * - Pop()            : 移除并返回最后一个节点的值（O(n)）
+ * - Shift()          : 移除并返回头节点的值（O(1)）
+ * - Unshift(value)   : 在链表头部插入节点（O(1)）
+ * - Find(cb)         : 根据回调函数查找第一个满足条件的节点
+ * - Remove(cb)       : 删除第一个满足条件的节点
+ * - Each(cb)         : 遍历所有节点
+ * - ToArray()        : 转换为普通数组
+ * - Size / IsEmpty   : 获取长度或判断是否为空
+ */
+class LinkedList {
+    constructor() {
+        this._head = null;
+        this._tail = null;
+        this._size = 0;
+    }
+    /** 链表当前长度 */
+    get Size() {
+        return this._size;
+    }
+    /** 链表是否为空 */
+    get IsEmpty() {
+        return this._size === 0;
+    }
+    /** 在尾部追加节点 */
+    Push(value) {
+        const node = new LinkedListNode(value);
+        if (!this._head) {
+            this._head = this._tail = node;
+        }
+        else {
+            this._tail.Next = node;
+            this._tail = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 在头部插入节点 */
+    Unshift(value) {
+        const node = new LinkedListNode(value);
+        if (!this._head) {
+            this._head = this._tail = node;
+        }
+        else {
+            node.Next = this._head;
+            this._head = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 移除并返回头节点的值 */
+    Shift() {
+        if (!this._head)
+            return undefined;
+        const value = this._head.Value;
+        this._head = this._head.Next;
+        if (!this._head)
+            this._tail = null; // 链表变空
+        this._size--;
+        return value;
+    }
+    /** 移除并返回尾节点的值（需要遍历） */
+    Pop() {
+        if (!this._head)
+            return undefined;
+        if (this._head === this._tail) {
+            // 只有一个节点
+            const value = this._head.Value;
+            this._head = this._tail = null;
+            this._size = 0;
+            return value;
+        }
+        // 找到倒数第二个节点
+        let prev = this._head;
+        while (prev.Next && prev.Next !== this._tail) {
+            prev = prev.Next;
+        }
+        const value = this._tail.Value;
+        prev.Next = null;
+        this._tail = prev;
+        this._size--;
+        return value;
+    }
+    /** 根据回调函数查找第一个满足条件的节点 */
+    Find(predicate) {
+        let current = this._head;
+        let idx = 0;
+        while (current) {
+            if (predicate(current.Value, idx))
+                return current;
+            current = current.Next;
+            idx++;
+        }
+        return null;
+    }
+    /** 删除第一个满足条件的节点，返回是否成功 */
+    Remove(predicate) {
+        if (!this._head)
+            return false;
+        // 删除头节点
+        if (predicate(this._head.Value, 0)) {
+            this.Shift();
+            return true;
+        }
+        let prev = this._head;
+        let current = this._head.Next;
+        let idx = 1;
+        while (current) {
+            if (predicate(current.Value, idx)) {
+                prev.Next = current.Next;
+                if (current === this._tail)
+                    this._tail = prev;
+                this._size--;
+                return true;
+            }
+            prev = current;
+            current = current.Next;
+            idx++;
+        }
+        return false;
+    }
+    /** 遍历所有节点；回调中新追加的节点不参与本次遍历，删除当前节点后沿原链继续 */
+    Each(callback) {
+        // 锚定起始尾节点：回调中 Push 会让原尾节点的 Next 指向新节点，
+        // 仅靠保存后继无法拦截，必须以起始尾节点为终点防止无限遍历
+        const end = this._tail;
+        let current = this._head;
+        let idx = 0;
+        while (current) {
+            // 提前保存后继：Remove 当前节点（其后继被改写）后也能继续沿原链走完
+            const next = current.Next;
+            callback(current.Value, idx);
+            if (current === end)
+                break;
+            current = next;
+            idx++;
+        }
+    }
+    /** 转换为普通数组 */
+    ToArray() {
+        const arr = [];
+        this.Each((v) => arr.push(v));
+        return arr;
+    }
+    /** 返回链表的字符串表示（调试用） */
+    toString() {
+        return this.ToArray().join(' -> ');
+    }
+}
+
+/**
+ * 泛型双向链表节点
+ */
+class DoublyLinkedListNode {
+    constructor(value) {
+        /** 前驱节点，链表头部为 null */
+        this.Prev = null;
+        /** 后继节点，链表尾部为 null */
+        this.Next = null;
+        this.Value = value;
+    }
+}
+/**
+ * 泛型双向链表
+ *
+ * 常用 API（时间复杂度已标注）：
+ * - Push(value)      : O(1)   在尾部追加
+ * - Unshift(value)   : O(1)   在头部插入
+ * - Pop()            : O(1)   移除并返回尾部节点
+ * - Shift()          : O(1)   移除并返回头部节点
+ * - InsertAfter(node, value) : O(1) 在指定节点后插入
+ * - InsertBefore(node, value): O(1) 在指定节点前插入
+ * - Remove(node)     : O(n)   删除任意节点（含归属校验）
+ * - Find(cb)         : O(n)   查找第一个满足条件的节点
+ * - Each(cb)         : O(n)   遍历
+ * - ToArray()        : O(n)   转为普通数组
+ */
+class DoublyLinkedList {
+    constructor() {
+        this._head = null;
+        this._tail = null;
+        this._size = 0;
+        /** 是否开启归属校验（防止误删/误插非本链表节点，开启后相关操作复杂度由 O(1) 变为 O(n)） */
+        this.CheckOwnership = false;
+    }
+    /** 链表当前长度 */
+    get Size() {
+        return this._size;
+    }
+    /** 链表是否为空 */
+    get IsEmpty() {
+        return this._size === 0;
+    }
+    /** 头节点（getter 只读，但节点字段可写；外部改写指针会破坏链表结构） */
+    get First() {
+        return this._head;
+    }
+    /** 尾节点（getter 只读，但节点字段可写；外部改写指针会破坏链表结构） */
+    get Last() {
+        return this._tail;
+    }
+    /** 在尾部追加节点 */
+    Push(value) {
+        const node = new DoublyLinkedListNode(value);
+        if (!this._tail) {
+            // 空链表
+            this._head = this._tail = node;
+        }
+        else {
+            node.Prev = this._tail;
+            this._tail.Next = node;
+            this._tail = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 在头部插入节点 */
+    Unshift(value) {
+        const node = new DoublyLinkedListNode(value);
+        if (!this._head) {
+            this._head = this._tail = node;
+        }
+        else {
+            node.Next = this._head;
+            this._head.Prev = node;
+            this._head = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 移除并返回头节点的值 */
+    Shift() {
+        if (!this._head)
+            return undefined;
+        const value = this._head.Value;
+        if (this._head === this._tail) {
+            // 只有一个节点
+            this._head = this._tail = null;
+        }
+        else {
+            const next = this._head.Next;
+            // 清理出链节点指针，缩短其引用链生命周期（与 Remove 行为一致）
+            this._head.Next = null;
+            next.Prev = null;
+            this._head = next;
+        }
+        this._size--;
+        return value;
+    }
+    /** 移除并返回尾节点的值 */
+    Pop() {
+        if (!this._tail)
+            return undefined;
+        const value = this._tail.Value;
+        if (this._head === this._tail) {
+            this._head = this._tail = null;
+        }
+        else {
+            const prev = this._tail.Prev;
+            // 清理出链节点指针，缩短其引用链生命周期（与 Remove 行为一致）
+            this._tail.Prev = null;
+            prev.Next = null;
+            this._tail = prev;
+        }
+        this._size--;
+        return value;
+    }
+    /**
+     * 在指定节点后插入新节点，返回新节点
+     * @tip 节点须属于本链表且未被移除，否则返回 null 且链表不受影响
+     */
+    InsertAfter(node, value) {
+        if (this.CheckOwnership && !this.owns(node))
+            return null;
+        const newNode = new DoublyLinkedListNode(value);
+        newNode.Prev = node;
+        newNode.Next = node.Next;
+        if (node.Next) {
+            node.Next.Prev = newNode;
+        }
+        else {
+            // node 是尾节点
+            this._tail = newNode;
+        }
+        node.Next = newNode;
+        this._size++;
+        return newNode;
+    }
+    /**
+     * 在指定节点前插入新节点，返回新节点
+     * @tip 节点须属于本链表且未被移除，否则返回 null 且链表不受影响
+     */
+    InsertBefore(node, value) {
+        if (this.CheckOwnership && !this.owns(node))
+            return null;
+        const newNode = new DoublyLinkedListNode(value);
+        newNode.Next = node;
+        newNode.Prev = node.Prev;
+        if (node.Prev) {
+            node.Prev.Next = newNode;
+        }
+        else {
+            // node 是头节点
+            this._head = newNode;
+        }
+        node.Prev = newNode;
+        this._size++;
+        return newNode;
+    }
+    /** 节点是否仍在链上（归属校验，O(n)） */
+    owns(node) {
+        let current = this._head;
+        while (current) {
+            if (current === node)
+                return true;
+            current = current.Next;
+        }
+        return false;
+    }
+    /**
+     * 删除任意节点，返回是否成功
+     * @tip 节点须属于本链表且未被移除，否则返回 false 且链表不受影响
+     */
+    Remove(node) {
+        // 归属校验：拦截来自其他链表或已被移除的节点，避免静默改写指针、错记 size
+        if (!node || (this.CheckOwnership && !this.owns(node)))
+            return false;
+        if (node.Prev) {
+            node.Prev.Next = node.Next;
+        }
+        else {
+            // 删除的是头节点
+            this._head = node.Next;
+        }
+        if (node.Next) {
+            node.Next.Prev = node.Prev;
+        }
+        else {
+            // 删除的是尾节点
+            this._tail = node.Prev;
+        }
+        // 清理被删节点的残留指针
+        node.Prev = null;
+        node.Next = null;
+        this._size--;
+        return true;
+    }
+    /** 根据回调函数查找第一个满足条件的节点 */
+    Find(predicate) {
+        let cur = this._head;
+        let idx = 0;
+        while (cur) {
+            if (predicate(cur.Value, idx))
+                return cur;
+            cur = cur.Next;
+            idx++;
+        }
+        return null;
+    }
+    /** 遍历所有节点；回调中新追加的节点不参与本次遍历，删除当前节点后沿原链继续 */
+    Each(callback) {
+        // 锚定起始尾节点：回调中 Push 会让原尾节点的 Next 指向新节点，
+        // 仅靠保存后继无法拦截，必须以起始尾节点为终点防止无限遍历
+        const end = this._tail;
+        let cur = this._head;
+        let idx = 0;
+        while (cur) {
+            // 提前保存后继：Remove 当前节点（会清空其指针）后也能继续沿原链走完
+            const next = cur.Next;
+            callback(cur.Value, idx);
+            if (cur === end)
+                break;
+            cur = next;
+            idx++;
+        }
+    }
+    /** 转换为普通数组（调试/展示用） */
+    ToArray() {
+        const arr = [];
+        this.Each((v) => arr.push(v));
+        return arr;
+    }
+    /** 便于调试的字符串表示 */
+    toString() {
+        return this.ToArray().join(' <-> ');
+    }
+}
+
+exports.DoublyLinkedList = DoublyLinkedList;
+exports.DoublyLinkedListNode = DoublyLinkedListNode;
+exports.LinkedList = LinkedList;
+exports.LinkedListNode = LinkedListNode;

package/dist/linked-list.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 泛型单向链表节点
+ */
+declare class LinkedListNode<T> {
+    /** 节点保存的值 */
+    Value: T;
+    /** 指向下一个节点，末尾为 null */
+    Next: LinkedListNode<T> | null;
+    constructor(value: T);
+}
+/**
+ * 泛型链表
+ *
+ * 主要方法：
+ * - Push(value)      : 在链表尾部追加节点
+ * - Pop()            : 移除并返回最后一个节点的值（O(n)）
+ * - Shift()          : 移除并返回头节点的值（O(1)）
+ * - Unshift(value)   : 在链表头部插入节点（O(1)）
+ * - Find(cb)         : 根据回调函数查找第一个满足条件的节点
+ * - Remove(cb)       : 删除第一个满足条件的节点
+ * - Each(cb)         : 遍历所有节点
+ * - ToArray()        : 转换为普通数组
+ * - Size / IsEmpty   : 获取长度或判断是否为空
+ */
+declare class LinkedList<T> {
+    private _head;
+    private _tail;
+    private _size;
+    /** 链表当前长度 */
+    get Size(): number;
+    /** 链表是否为空 */
+    get IsEmpty(): boolean;
+    /** 在尾部追加节点 */
+    Push(value: T): this;
+    /** 在头部插入节点 */
+    Unshift(value: T): this;
+    /** 移除并返回头节点的值 */
+    Shift(): T | undefined;
+    /** 移除并返回尾节点的值（需要遍历） */
+    Pop(): T | undefined;
+    /** 根据回调函数查找第一个满足条件的节点 */
+    Find(predicate: (value: T, index: number) => boolean): LinkedListNode<T> | null;
+    /** 删除第一个满足条件的节点，返回是否成功 */
+    Remove(predicate: (value: T, index: number) => boolean): boolean;
+    /** 遍历所有节点；回调中新追加的节点不参与本次遍历，删除当前节点后沿原链继续 */
+    Each(callback: (value: T, index: number) => void): void;
+    /** 转换为普通数组 */
+    ToArray(): T[];
+    /** 返回链表的字符串表示（调试用） */
+    toString(): string;
+}
+
+/**
+ * 泛型双向链表节点
+ */
+declare class DoublyLinkedListNode<T> {
+    /** 保存的值 */
+    Value: T;
+    /** 前驱节点，链表头部为 null */
+    Prev: DoublyLinkedListNode<T> | null;
+    /** 后继节点，链表尾部为 null */
+    Next: DoublyLinkedListNode<T> | null;
+    constructor(value: T);
+}
+/**
+ * 泛型双向链表
+ *
+ * 常用 API（时间复杂度已标注）：
+ * - Push(value)      : O(1)   在尾部追加
+ * - Unshift(value)   : O(1)   在头部插入
+ * - Pop()            : O(1)   移除并返回尾部节点
+ * - Shift()          : O(1)   移除并返回头部节点
+ * - InsertAfter(node, value) : O(1) 在指定节点后插入
+ * - InsertBefore(node, value): O(1) 在指定节点前插入
+ * - Remove(node)     : O(n)   删除任意节点（含归属校验）
+ * - Find(cb)         : O(n)   查找第一个满足条件的节点
+ * - Each(cb)         : O(n)   遍历
+ * - ToArray()        : O(n)   转为普通数组
+ */
+declare class DoublyLinkedList<T> {
+    private _head;
+    private _tail;
+    private _size;
+    /** 是否开启归属校验（防止误删/误插非本链表节点，开启后相关操作复杂度由 O(1) 变为 O(n)） */
+    CheckOwnership: boolean;
+    /** 链表当前长度 */
+    get Size(): number;
+    /** 链表是否为空 */
+    get IsEmpty(): boolean;
+    /** 头节点（getter 只读，但节点字段可写；外部改写指针会破坏链表结构） */
+    get First(): DoublyLinkedListNode<T> | null;
+    /** 尾节点（getter 只读，但节点字段可写；外部改写指针会破坏链表结构） */
+    get Last(): DoublyLinkedListNode<T> | null;
+    /** 在尾部追加节点 */
+    Push(value: T): this;
+    /** 在头部插入节点 */
+    Unshift(value: T): this;
+    /** 移除并返回头节点的值 */
+    Shift(): T | undefined;
+    /** 移除并返回尾节点的值 */
+    Pop(): T | undefined;
+    /**
+     * 在指定节点后插入新节点，返回新节点
+     * @tip 节点须属于本链表且未被移除，否则返回 null 且链表不受影响
+     */
+    InsertAfter(node: DoublyLinkedListNode<T>, value: T): DoublyLinkedListNode<T> | null;
+    /**
+     * 在指定节点前插入新节点，返回新节点
+     * @tip 节点须属于本链表且未被移除，否则返回 null 且链表不受影响
+     */
+    InsertBefore(node: DoublyLinkedListNode<T>, value: T): DoublyLinkedListNode<T> | null;
+    /** 节点是否仍在链上（归属校验，O(n)） */
+    private owns;
+    /**
+     * 删除任意节点，返回是否成功
+     * @tip 节点须属于本链表且未被移除，否则返回 false 且链表不受影响
+     */
+    Remove(node: DoublyLinkedListNode<T>): boolean;
+    /** 根据回调函数查找第一个满足条件的节点 */
+    Find(predicate: (value: T, index: number) => boolean): DoublyLinkedListNode<T> | null;
+    /** 遍历所有节点；回调中新追加的节点不参与本次遍历，删除当前节点后沿原链继续 */
+    Each(callback: (value: T, index: number) => void): void;
+    /** 转换为普通数组（调试/展示用） */
+    ToArray(): T[];
+    /** 便于调试的字符串表示 */
+    toString(): string;
+}
+
+export { DoublyLinkedList, DoublyLinkedListNode, LinkedList, LinkedListNode };

package/dist/linked-list.min.cjs

@@ -0,0 +1 @@
+"use strict";class t{constructor(t){this.Next=null,this.Value=t}}class e{constructor(t){this.Prev=null,this.Next=null,this.Value=t}}exports.DoublyLinkedList=class{constructor(){this._head=null,this._tail=null,this._size=0,this.CheckOwnership=!1}get Size(){return this._size}get IsEmpty(){return 0===this._size}get First(){return this._head}get Last(){return this._tail}Push(t){const i=new e(t);return this._tail?(i.Prev=this._tail,this._tail.Next=i,this._tail=i):this._head=this._tail=i,this._size++,this}Unshift(t){const i=new e(t);return this._head?(i.Next=this._head,this._head.Prev=i,this._head=i):this._head=this._tail=i,this._size++,this}Shift(){if(!this._head)return;const t=this._head.Value;if(this._head===this._tail)this._head=this._tail=null;else{const t=this._head.Next;this._head.Next=null,t.Prev=null,this._head=t}return this._size--,t}Pop(){if(!this._tail)return;const t=this._tail.Value;if(this._head===this._tail)this._head=this._tail=null;else{const t=this._tail.Prev;this._tail.Prev=null,t.Next=null,this._tail=t}return this._size--,t}InsertAfter(t,i){if(this.CheckOwnership&&!this.owns(t))return null;const s=new e(i);return s.Prev=t,s.Next=t.Next,t.Next?t.Next.Prev=s:this._tail=s,t.Next=s,this._size++,s}InsertBefore(t,i){if(this.CheckOwnership&&!this.owns(t))return null;const s=new e(i);return s.Next=t,s.Prev=t.Prev,t.Prev?t.Prev.Next=s:this._head=s,t.Prev=s,this._size++,s}owns(t){let e=this._head;for(;e;){if(e===t)return!0;e=e.Next}return!1}Remove(t){return!(!t||this.CheckOwnership&&!this.owns(t))&&(t.Prev?t.Prev.Next=t.Next:this._head=t.Next,t.Next?t.Next.Prev=t.Prev:this._tail=t.Prev,t.Prev=null,t.Next=null,this._size--,!0)}Find(t){let e=this._head,i=0;for(;e;){if(t(e.Value,i))return e;e=e.Next,i++}return null}Each(t){const e=this._tail;let i=this._head,s=0;for(;i;){const h=i.Next;if(t(i.Value,s),i===e)break;i=h,s++}}ToArray(){const t=[];return this.Each(e=>t.push(e)),t}toString(){return this.ToArray().join(" <-> ")}},exports.DoublyLinkedListNode=e,exports.LinkedList=class{constructor(){this._head=null,this._tail=null,this._size=0}get Size(){return this._size}get IsEmpty(){return 0===this._size}Push(e){const i=new t(e);return this._head?(this._tail.Next=i,this._tail=i):this._head=this._tail=i,this._size++,this}Unshift(e){const i=new t(e);return this._head?(i.Next=this._head,this._head=i):this._head=this._tail=i,this._size++,this}Shift(){if(!this._head)return;const t=this._head.Value;return this._head=this._head.Next,this._head||(this._tail=null),this._size--,t}Pop(){if(!this._head)return;if(this._head===this._tail){const t=this._head.Value;return this._head=this._tail=null,this._size=0,t}let t=this._head;for(;t.Next&&t.Next!==this._tail;)t=t.Next;const e=this._tail.Value;return t.Next=null,this._tail=t,this._size--,e}Find(t){let e=this._head,i=0;for(;e;){if(t(e.Value,i))return e;e=e.Next,i++}return null}Remove(t){if(!this._head)return!1;if(t(this._head.Value,0))return this.Shift(),!0;let e=this._head,i=this._head.Next,s=1;for(;i;){if(t(i.Value,s))return e.Next=i.Next,i===this._tail&&(this._tail=e),this._size--,!0;e=i,i=i.Next,s++}return!1}Each(t){const e=this._tail;let i=this._head,s=0;for(;i;){const h=i.Next;if(t(i.Value,s),i===e)break;i=h,s++}}ToArray(){const t=[];return this.Each(e=>t.push(e)),t}toString(){return this.ToArray().join(" -> ")}},exports.LinkedListNode=t;

package/dist/linked-list.min.mjs

@@ -0,0 +1 @@
+class t{constructor(t){this.Next=null,this.Value=t}}class e{constructor(){this._head=null,this._tail=null,this._size=0}get Size(){return this._size}get IsEmpty(){return 0===this._size}Push(e){const i=new t(e);return this._head?(this._tail.Next=i,this._tail=i):this._head=this._tail=i,this._size++,this}Unshift(e){const i=new t(e);return this._head?(i.Next=this._head,this._head=i):this._head=this._tail=i,this._size++,this}Shift(){if(!this._head)return;const t=this._head.Value;return this._head=this._head.Next,this._head||(this._tail=null),this._size--,t}Pop(){if(!this._head)return;if(this._head===this._tail){const t=this._head.Value;return this._head=this._tail=null,this._size=0,t}let t=this._head;for(;t.Next&&t.Next!==this._tail;)t=t.Next;const e=this._tail.Value;return t.Next=null,this._tail=t,this._size--,e}Find(t){let e=this._head,i=0;for(;e;){if(t(e.Value,i))return e;e=e.Next,i++}return null}Remove(t){if(!this._head)return!1;if(t(this._head.Value,0))return this.Shift(),!0;let e=this._head,i=this._head.Next,s=1;for(;i;){if(t(i.Value,s))return e.Next=i.Next,i===this._tail&&(this._tail=e),this._size--,!0;e=i,i=i.Next,s++}return!1}Each(t){const e=this._tail;let i=this._head,s=0;for(;i;){const h=i.Next;if(t(i.Value,s),i===e)break;i=h,s++}}ToArray(){const t=[];return this.Each(e=>t.push(e)),t}toString(){return this.ToArray().join(" -> ")}}class i{constructor(t){this.Prev=null,this.Next=null,this.Value=t}}class s{constructor(){this._head=null,this._tail=null,this._size=0,this.CheckOwnership=!1}get Size(){return this._size}get IsEmpty(){return 0===this._size}get First(){return this._head}get Last(){return this._tail}Push(t){const e=new i(t);return this._tail?(e.Prev=this._tail,this._tail.Next=e,this._tail=e):this._head=this._tail=e,this._size++,this}Unshift(t){const e=new i(t);return this._head?(e.Next=this._head,this._head.Prev=e,this._head=e):this._head=this._tail=e,this._size++,this}Shift(){if(!this._head)return;const t=this._head.Value;if(this._head===this._tail)this._head=this._tail=null;else{const t=this._head.Next;this._head.Next=null,t.Prev=null,this._head=t}return this._size--,t}Pop(){if(!this._tail)return;const t=this._tail.Value;if(this._head===this._tail)this._head=this._tail=null;else{const t=this._tail.Prev;this._tail.Prev=null,t.Next=null,this._tail=t}return this._size--,t}InsertAfter(t,e){if(this.CheckOwnership&&!this.owns(t))return null;const s=new i(e);return s.Prev=t,s.Next=t.Next,t.Next?t.Next.Prev=s:this._tail=s,t.Next=s,this._size++,s}InsertBefore(t,e){if(this.CheckOwnership&&!this.owns(t))return null;const s=new i(e);return s.Next=t,s.Prev=t.Prev,t.Prev?t.Prev.Next=s:this._head=s,t.Prev=s,this._size++,s}owns(t){let e=this._head;for(;e;){if(e===t)return!0;e=e.Next}return!1}Remove(t){return!(!t||this.CheckOwnership&&!this.owns(t))&&(t.Prev?t.Prev.Next=t.Next:this._head=t.Next,t.Next?t.Next.Prev=t.Prev:this._tail=t.Prev,t.Prev=null,t.Next=null,this._size--,!0)}Find(t){let e=this._head,i=0;for(;e;){if(t(e.Value,i))return e;e=e.Next,i++}return null}Each(t){const e=this._tail;let i=this._head,s=0;for(;i;){const h=i.Next;if(t(i.Value,s),i===e)break;i=h,s++}}ToArray(){const t=[];return this.Each(e=>t.push(e)),t}toString(){return this.ToArray().join(" <-> ")}}export{s as DoublyLinkedList,i as DoublyLinkedListNode,e as LinkedList,t as LinkedListNode};

package/dist/linked-list.mjs

@@ -0,0 +1,403 @@
+/**
+ * 泛型单向链表节点
+ */
+class LinkedListNode {
+    constructor(value) {
+        /** 指向下一个节点，末尾为 null */
+        this.Next = null;
+        this.Value = value;
+    }
+}
+/**
+ * 泛型链表
+ *
+ * 主要方法：
+ * - Push(value)      : 在链表尾部追加节点
+ * - Pop()            : 移除并返回最后一个节点的值（O(n)）
+ * - Shift()          : 移除并返回头节点的值（O(1)）
+ * - Unshift(value)   : 在链表头部插入节点（O(1)）
+ * - Find(cb)         : 根据回调函数查找第一个满足条件的节点
+ * - Remove(cb)       : 删除第一个满足条件的节点
+ * - Each(cb)         : 遍历所有节点
+ * - ToArray()        : 转换为普通数组
+ * - Size / IsEmpty   : 获取长度或判断是否为空
+ */
+class LinkedList {
+    constructor() {
+        this._head = null;
+        this._tail = null;
+        this._size = 0;
+    }
+    /** 链表当前长度 */
+    get Size() {
+        return this._size;
+    }
+    /** 链表是否为空 */
+    get IsEmpty() {
+        return this._size === 0;
+    }
+    /** 在尾部追加节点 */
+    Push(value) {
+        const node = new LinkedListNode(value);
+        if (!this._head) {
+            this._head = this._tail = node;
+        }
+        else {
+            this._tail.Next = node;
+            this._tail = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 在头部插入节点 */
+    Unshift(value) {
+        const node = new LinkedListNode(value);
+        if (!this._head) {
+            this._head = this._tail = node;
+        }
+        else {
+            node.Next = this._head;
+            this._head = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 移除并返回头节点的值 */
+    Shift() {
+        if (!this._head)
+            return undefined;
+        const value = this._head.Value;
+        this._head = this._head.Next;
+        if (!this._head)
+            this._tail = null; // 链表变空
+        this._size--;
+        return value;
+    }
+    /** 移除并返回尾节点的值（需要遍历） */
+    Pop() {
+        if (!this._head)
+            return undefined;
+        if (this._head === this._tail) {
+            // 只有一个节点
+            const value = this._head.Value;
+            this._head = this._tail = null;
+            this._size = 0;
+            return value;
+        }
+        // 找到倒数第二个节点
+        let prev = this._head;
+        while (prev.Next && prev.Next !== this._tail) {
+            prev = prev.Next;
+        }
+        const value = this._tail.Value;
+        prev.Next = null;
+        this._tail = prev;
+        this._size--;
+        return value;
+    }
+    /** 根据回调函数查找第一个满足条件的节点 */
+    Find(predicate) {
+        let current = this._head;
+        let idx = 0;
+        while (current) {
+            if (predicate(current.Value, idx))
+                return current;
+            current = current.Next;
+            idx++;
+        }
+        return null;
+    }
+    /** 删除第一个满足条件的节点，返回是否成功 */
+    Remove(predicate) {
+        if (!this._head)
+            return false;
+        // 删除头节点
+        if (predicate(this._head.Value, 0)) {
+            this.Shift();
+            return true;
+        }
+        let prev = this._head;
+        let current = this._head.Next;
+        let idx = 1;
+        while (current) {
+            if (predicate(current.Value, idx)) {
+                prev.Next = current.Next;
+                if (current === this._tail)
+                    this._tail = prev;
+                this._size--;
+                return true;
+            }
+            prev = current;
+            current = current.Next;
+            idx++;
+        }
+        return false;
+    }
+    /** 遍历所有节点；回调中新追加的节点不参与本次遍历，删除当前节点后沿原链继续 */
+    Each(callback) {
+        // 锚定起始尾节点：回调中 Push 会让原尾节点的 Next 指向新节点，
+        // 仅靠保存后继无法拦截，必须以起始尾节点为终点防止无限遍历
+        const end = this._tail;
+        let current = this._head;
+        let idx = 0;
+        while (current) {
+            // 提前保存后继：Remove 当前节点（其后继被改写）后也能继续沿原链走完
+            const next = current.Next;
+            callback(current.Value, idx);
+            if (current === end)
+                break;
+            current = next;
+            idx++;
+        }
+    }
+    /** 转换为普通数组 */
+    ToArray() {
+        const arr = [];
+        this.Each((v) => arr.push(v));
+        return arr;
+    }
+    /** 返回链表的字符串表示（调试用） */
+    toString() {
+        return this.ToArray().join(' -> ');
+    }
+}
+
+/**
+ * 泛型双向链表节点
+ */
+class DoublyLinkedListNode {
+    constructor(value) {
+        /** 前驱节点，链表头部为 null */
+        this.Prev = null;
+        /** 后继节点，链表尾部为 null */
+        this.Next = null;
+        this.Value = value;
+    }
+}
+/**
+ * 泛型双向链表
+ *
+ * 常用 API（时间复杂度已标注）：
+ * - Push(value)      : O(1)   在尾部追加
+ * - Unshift(value)   : O(1)   在头部插入
+ * - Pop()            : O(1)   移除并返回尾部节点
+ * - Shift()          : O(1)   移除并返回头部节点
+ * - InsertAfter(node, value) : O(1) 在指定节点后插入
+ * - InsertBefore(node, value): O(1) 在指定节点前插入
+ * - Remove(node)     : O(n)   删除任意节点（含归属校验）
+ * - Find(cb)         : O(n)   查找第一个满足条件的节点
+ * - Each(cb)         : O(n)   遍历
+ * - ToArray()        : O(n)   转为普通数组
+ */
+class DoublyLinkedList {
+    constructor() {
+        this._head = null;
+        this._tail = null;
+        this._size = 0;
+        /** 是否开启归属校验（防止误删/误插非本链表节点，开启后相关操作复杂度由 O(1) 变为 O(n)） */
+        this.CheckOwnership = false;
+    }
+    /** 链表当前长度 */
+    get Size() {
+        return this._size;
+    }
+    /** 链表是否为空 */
+    get IsEmpty() {
+        return this._size === 0;
+    }
+    /** 头节点（getter 只读，但节点字段可写；外部改写指针会破坏链表结构） */
+    get First() {
+        return this._head;
+    }
+    /** 尾节点（getter 只读，但节点字段可写；外部改写指针会破坏链表结构） */
+    get Last() {
+        return this._tail;
+    }
+    /** 在尾部追加节点 */
+    Push(value) {
+        const node = new DoublyLinkedListNode(value);
+        if (!this._tail) {
+            // 空链表
+            this._head = this._tail = node;
+        }
+        else {
+            node.Prev = this._tail;
+            this._tail.Next = node;
+            this._tail = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 在头部插入节点 */
+    Unshift(value) {
+        const node = new DoublyLinkedListNode(value);
+        if (!this._head) {
+            this._head = this._tail = node;
+        }
+        else {
+            node.Next = this._head;
+            this._head.Prev = node;
+            this._head = node;
+        }
+        this._size++;
+        return this;
+    }
+    /** 移除并返回头节点的值 */
+    Shift() {
+        if (!this._head)
+            return undefined;
+        const value = this._head.Value;
+        if (this._head === this._tail) {
+            // 只有一个节点
+            this._head = this._tail = null;
+        }
+        else {
+            const next = this._head.Next;
+            // 清理出链节点指针，缩短其引用链生命周期（与 Remove 行为一致）
+            this._head.Next = null;
+            next.Prev = null;
+            this._head = next;
+        }
+        this._size--;
+        return value;
+    }
+    /** 移除并返回尾节点的值 */
+    Pop() {
+        if (!this._tail)
+            return undefined;
+        const value = this._tail.Value;
+        if (this._head === this._tail) {
+            this._head = this._tail = null;
+        }
+        else {
+            const prev = this._tail.Prev;
+            // 清理出链节点指针，缩短其引用链生命周期（与 Remove 行为一致）
+            this._tail.Prev = null;
+            prev.Next = null;
+            this._tail = prev;
+        }
+        this._size--;
+        return value;
+    }
+    /**
+     * 在指定节点后插入新节点，返回新节点
+     * @tip 节点须属于本链表且未被移除，否则返回 null 且链表不受影响
+     */
+    InsertAfter(node, value) {
+        if (this.CheckOwnership && !this.owns(node))
+            return null;
+        const newNode = new DoublyLinkedListNode(value);
+        newNode.Prev = node;
+        newNode.Next = node.Next;
+        if (node.Next) {
+            node.Next.Prev = newNode;
+        }
+        else {
+            // node 是尾节点
+            this._tail = newNode;
+        }
+        node.Next = newNode;
+        this._size++;
+        return newNode;
+    }
+    /**
+     * 在指定节点前插入新节点，返回新节点
+     * @tip 节点须属于本链表且未被移除，否则返回 null 且链表不受影响
+     */
+    InsertBefore(node, value) {
+        if (this.CheckOwnership && !this.owns(node))
+            return null;
+        const newNode = new DoublyLinkedListNode(value);
+        newNode.Next = node;
+        newNode.Prev = node.Prev;
+        if (node.Prev) {
+            node.Prev.Next = newNode;
+        }
+        else {
+            // node 是头节点
+            this._head = newNode;
+        }
+        node.Prev = newNode;
+        this._size++;
+        return newNode;
+    }
+    /** 节点是否仍在链上（归属校验，O(n)） */
+    owns(node) {
+        let current = this._head;
+        while (current) {
+            if (current === node)
+                return true;
+            current = current.Next;
+        }
+        return false;
+    }
+    /**
+     * 删除任意节点，返回是否成功
+     * @tip 节点须属于本链表且未被移除，否则返回 false 且链表不受影响
+     */
+    Remove(node) {
+        // 归属校验：拦截来自其他链表或已被移除的节点，避免静默改写指针、错记 size
+        if (!node || (this.CheckOwnership && !this.owns(node)))
+            return false;
+        if (node.Prev) {
+            node.Prev.Next = node.Next;
+        }
+        else {
+            // 删除的是头节点
+            this._head = node.Next;
+        }
+        if (node.Next) {
+            node.Next.Prev = node.Prev;
+        }
+        else {
+            // 删除的是尾节点
+            this._tail = node.Prev;
+        }
+        // 清理被删节点的残留指针
+        node.Prev = null;
+        node.Next = null;
+        this._size--;
+        return true;
+    }
+    /** 根据回调函数查找第一个满足条件的节点 */
+    Find(predicate) {
+        let cur = this._head;
+        let idx = 0;
+        while (cur) {
+            if (predicate(cur.Value, idx))
+                return cur;
+            cur = cur.Next;
+            idx++;
+        }
+        return null;
+    }
+    /** 遍历所有节点；回调中新追加的节点不参与本次遍历，删除当前节点后沿原链继续 */
+    Each(callback) {
+        // 锚定起始尾节点：回调中 Push 会让原尾节点的 Next 指向新节点，
+        // 仅靠保存后继无法拦截，必须以起始尾节点为终点防止无限遍历
+        const end = this._tail;
+        let cur = this._head;
+        let idx = 0;
+        while (cur) {
+            // 提前保存后继：Remove 当前节点（会清空其指针）后也能继续沿原链走完
+            const next = cur.Next;
+            callback(cur.Value, idx);
+            if (cur === end)
+                break;
+            cur = next;
+            idx++;
+        }
+    }
+    /** 转换为普通数组（调试/展示用） */
+    ToArray() {
+        const arr = [];
+        this.Each((v) => arr.push(v));
+        return arr;
+    }
+    /** 便于调试的字符串表示 */
+    toString() {
+        return this.ToArray().join(' <-> ');
+    }
+}
+
+export { DoublyLinkedList, DoublyLinkedListNode, LinkedList, LinkedListNode };

package/dist/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@nebulaaa/linked-list",
+  "version": "2.0.0",
+  "description": "链表扩展包",
+  "author": "doooreyn",
+  "license": "MIT",
+  "keywords": [
+    "linked-list",
+    "nebulaaa"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "main": "./linked-list.cjs",
+  "module": "./linked-list.mjs",
+  "types": "./linked-list.d.ts",
+  "exports": {
+    ".": {
+      "types": "./linked-list.d.ts",
+      "require": "./linked-list.cjs",
+      "import": "./linked-list.mjs",
+      "default": "./linked-list.cjs"
+    },
+    "./min": {
+      "types": "./linked-list.d.ts",
+      "require": "./linked-list.min.cjs",
+      "import": "./linked-list.min.mjs"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/package.json

@@ -1,6 +1,66 @@
-{
-  "name": "@nebulaaa/linked-list",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@nebulaaa/linked-list",
+  "version": "2.0.0",
+  "description": "链表扩展包",
+  "main": "./dist/linked-list.cjs",
+  "module": "./dist/linked-list.mjs",
+  "types": "./dist/linked-list.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/linked-list.cjs",
+      "import": "./dist/linked-list.mjs",
+      "types": "./dist/linked-list.d.ts",
+      "default": "./dist/linked-list.cjs"
+    },
+    "./min": {
+      "require": "./dist/linked-list.min.cjs",
+      "import": "./dist/linked-list.min.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && rollup -c rollup.config.mjs && node ../scripts/write-dist-package.mjs linked-list",
+    "test": "jest"
+  },
+  "keywords": [
+    "linked-list",
+    "nebulaaa"
+  ],
+  "author": "doooreyn",
+  "license": "MIT",
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=10.0.0",
+      "onFail": "warn"
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "allowScripts": {
+    "unrs-resolver@1.12.2": true,
+    "@parcel/watcher@2.6.0": true
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.2",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "jest": "^30.5.2",
+    "rollup": "^4.28.1",
+    "rollup-plugin-dts": "^6.1.1",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "5.7.3"
+  },
+  "dependencies": {}
+}